# qosil/ai_memory_open architecture

> Architecture diagram of the GitHub repository qosil/ai_memory_open, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qosil/ai_memory_open
- Repository: https://github.com/qosil/ai_memory_open

## Overview

1. **Repository role**
   - This is not a conventional product app; it is a **memory-and-governance framework for AI-assisted work**. The primary runtime is an AI assistant with filesystem access, and **git is the persistence layer** for all memory, decisions, and session continuity.

2. **Core control plane**
   - The top-level files form the operating core: `Master-AI-Context.md`, `setup-AI-Memory.md`, `staging.md`, `PROJECT_MEMORY_INIT.md`, `NextSteps.md`, `Key-Decisions.md`, `Sessions.md`, and `Risk-Registry.md`.
   - These files define how an AI starts, plans, executes, and resumes work across sessions.

3. **Session lifecycle boundary**
   - The repository enforces a three-phase lifecycle through `agents/open.md` and `agents/closure.md`:
     - **Open:** load context, read indexes, initialize live session files.
     - **Work:** update session/decision logs incrementally.
     - **Close:** finalize logs, update indexes, and persist changes back to git.
   - This creates a clear boundary between transient session state and durable project memory.

4. **Tiered memory model**
   - The README describes a **3-tier lazy-loading pattern**:
     - **Tier 1:** always-read context (`Master-AI-Context.md`, architecture file, module map, next steps).
     - **Tier 2:** index files for selective lookup (`Key-Decisions.md`, `Sessions.md`, `Risk-Registry.md`, standards).
     - **Tier 3:** on-demand detailed artifacts such as release plans, specs, and connector configs.
   - Architecturally, this is a knowledge retrieval system optimized to avoid overloading the AI context window.

5. **Persistent knowledge stores**
   - `decisions-learnings/`, `session-summary/`, `contacts/`, and the index files are the durable memory layer.
   - `contacts/` introduces a structured profiling subsystem for communication preferences, while the decision/session files preserve traceability of why choices were made and what happened in prior sessions.

6. **Governance and standards**
   - `Standards and Policy/` is the policy layer, with master standards for operating practice and communication.
   - These standards act as cross-cutting constraints over all projects and sessions, shaping execution authority, communication style, and decision-making rules.

7. **Domain expert agent library**
   - `Memory_Agents/` is a large catalog of domain-specific advisor templates, each with an `AGENT.md` and a domain playbook.
   - The structure includes areas such as Finance, Legal, Marketing, Operations, Sales, Strategy, Software Development, Infrastructure, Product Development, People & Culture, and more.
   - These are not runtime services; they are **specialized reasoning modules** that can be deployed into project folders during initialization.

8. **Project staging and project workspace**
   - `projects/` is the destination for actual work, with `projects/staging/` used for projects in planning or ideation.
   - The repo’s lifecycle suggests a progression from **setup → staging → project memory initialization**, after which a project gets its own structured folder and context files.
   - This is the main boundary between the reusable template system and each concrete project instance.

9. **Validation and methodology artifacts**
   - `Model_Validation/` contains white papers and planning documents that validate the underlying memory methodology and process design.
   - These documents act as the research and rationale layer, supporting the operating model rather than serving as runtime inputs.

10. **Zoho connector subsystem**
   - `zoho-mcp-server/` is the only conventional software component: a **Node.js MCP server** that exposes Zoho integrations.
   - It is organized around `src/auth.js`, `src/index.js`, `src/setup.js`, and tool modules for `books`, `campaigns`, `crm`, `desk`, `projects`, `sign`, and `sprints`.
   - Its architecture is a connector boundary to external SaaS services, configured via Zoho API credentials and Claude desktop configuration.

11. **External dependencies and integration points**
   - The repository depends on:
     - **Git** for versioned persistence and collaboration.
     - **An AI assistant** for reading/writing the memory files and executing the lifecycle.
     - **Zoho APIs** for the MCP server.
   - There is no central database or application backend; the filesystem and version control system are the system of record.

12. **Overall system diagram implication**
   - A useful architecture diagram should show:
     - AI assistant as the primary actor.
     - Git-backed memory repository as the durable context store.
     - Standards and indexes as governance and retrieval layers.
     - Domain agents as reusable advisory modules.
     - Project folders as instantiated workspaces.
     - Zoho MCP server as the only external-service integration runtime.

Main entry points: [`agents/open.md`](https://github.com/qosil/ai_memory_open/blob/main/agents/open.md) (Open/Close), [`Memory_Agents`](https://github.com/qosil/ai_memory_open/tree/main/Memory_Agents) (Domain Agents), [`zoho-mcp-server/src/index.js`](https://github.com/qosil/ai_memory_open/blob/main/zoho-mcp-server/src/index.js) (Zoho MCP), [`Standards and Policy/CCDE-Operating-Standard.md`](https://github.com/qosil/ai_memory_open/blob/HEAD/Standards%20and%20Policy/CCDE-Operating-Standard.md) (Standards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Memory Core"]
  node_n2["Master Context<br/>control-plane"]
  node_n3["Setup Guide<br/>bootstrap<br/>[setup-AI-Memory.md]"]
  node_n4["Staging Flow<br/>workflow<br/>[staging.md]"]
  node_n5["Memory Init<br/>bootstrap"]
  node_n6["Next Steps<br/>planning index<br/>[NextSteps.md]"]
  node_n7["Key Decisions<br/>decision log<br/>[Key-Decisions.md]"]
  node_n8["Sessions<br/>session log<br/>[Sessions.md]"]
  node_n9["Risk Registry<br/>risk log<br/>[Risk-Registry.md]"]
  node_n20[("Memory Stores<br/>durable memory")]
  node_n21[("Contacts<br/>profile store")]
end

subgraph group_g2["Governance"]
  node_n10["Open/Close<br/>lifecycle rules<br/>[open.md]"]
  node_n11["Closure Rules<br/>lifecycle rules<br/>[closure.md]"]
  node_n12["Standards<br/>policy layer"]
  node_n13["Comm Standard<br/>policy layer"]
end

subgraph group_g3["Advisor Library"]
  node_n14[("Domain Agents<br/>advisor library")]
  node_n15["Strategy<br/>advisor pack"]
  node_n16["Operations<br/>advisor pack"]
  node_n17["Software Dev<br/>advisor pack"]
end

subgraph group_g4["Project Workspaces"]
  node_n18[("Projects<br/>workspace root")]
  node_n19[("Staging Area<br/>project staging")]
end

subgraph group_g5["Validation"]
  node_n22[("Validation Library<br/>research base")]
  node_n23["Whitepaper Gen<br/>document generator"]
end

subgraph group_g6["Zoho Connector"]
  node_n24["Zoho MCP<br/>integration runtime<br/>[index.js]"]
  node_n25["Auth Setup<br/>integration auth<br/>[auth.js]"]
  node_n26[("Tool Modules<br/>integration tools")]
end

node_n1(("AI Assistant<br/>actor"))

node_n1 -->|"loads"| node_n2
node_n1 -->|"initializes"| node_n3
node_n1 -->|"opens"| node_n10
node_n1 -->|"closes"| node_n11
node_n10 -->|"reads"| node_n2
node_n10 -->|"indexes"| node_n7
node_n10 -->|"indexes"| node_n8
node_n10 -->|"indexes"| node_n9
node_n1 -->|"plans"| node_n6
node_n1 -->|"constrained by"| node_n12
node_n1 -->|"communicates by"| node_n13
node_n14 -->|"contains"| node_n15
node_n14 -->|"contains"| node_n16
node_n14 -->|"contains"| node_n17
node_n1 -->|"deploys"| node_n14
node_n1 -->|"works in"| node_n18
node_n18 -->|"starts in"| node_n19
node_n1 -->|"persists"| node_n20
node_n1 -->|"profiles"| node_n21
node_n1 -->|"studies"| node_n22
node_n22 -->|"generates"| node_n23
node_n1 -->|"invokes"| node_n24
node_n24 -->|"uses"| node_n25
node_n24 -->|"exposes"| node_n26
node_n26 -->|"served by"| node_n24
node_n12 -->|"governs"| node_n10
node_n12 -->|"governs"| node_n1
node_n18 -->|"initialized by"| node_n5
node_n7 -->|"cross-references"| node_n8

click node_n2 "https://github.com/qosil/ai_memory_open/blob/main/Master-AI-Context.md"
click node_n3 "https://github.com/qosil/ai_memory_open/blob/main/setup-AI-Memory.md"
click node_n4 "https://github.com/qosil/ai_memory_open/blob/main/staging.md"
click node_n5 "https://github.com/qosil/ai_memory_open/blob/main/PROJECT_MEMORY_INIT.md"
click node_n6 "https://github.com/qosil/ai_memory_open/blob/main/NextSteps.md"
click node_n7 "https://github.com/qosil/ai_memory_open/blob/main/Key-Decisions.md"
click node_n8 "https://github.com/qosil/ai_memory_open/blob/main/Sessions.md"
click node_n9 "https://github.com/qosil/ai_memory_open/blob/main/Risk-Registry.md"
click node_n10 "https://github.com/qosil/ai_memory_open/blob/main/agents/open.md"
click node_n11 "https://github.com/qosil/ai_memory_open/blob/main/agents/closure.md"
click node_n12 "https://github.com/qosil/ai_memory_open/blob/main/Standards and Policy/CCDE-Operating-Standard.md"
click node_n13 "https://github.com/qosil/ai_memory_open/blob/main/Standards and Policy/Communication-Standard.md"
click node_n14 "https://github.com/qosil/ai_memory_open/tree/main/Memory_Agents"
click node_n15 "https://github.com/qosil/ai_memory_open/blob/main/Memory_Agents/Strategy/strategy-advisor.md"
click node_n16 "https://github.com/qosil/ai_memory_open/blob/main/Memory_Agents/Operations/operations-advisor.md"
click node_n17 "https://github.com/qosil/ai_memory_open/blob/main/Memory_Agents/Software-Development/software-development-advisor.md"
click node_n18 "https://github.com/qosil/ai_memory_open/tree/main/projects"
click node_n19 "https://github.com/qosil/ai_memory_open/tree/main/projects/staging"
click node_n20 "https://github.com/qosil/ai_memory_open/tree/main/session-summary"
click node_n21 "https://github.com/qosil/ai_memory_open/tree/main/contacts"
click node_n22 "https://github.com/qosil/ai_memory_open/tree/main/Model_Validation"
click node_n23 "https://github.com/qosil/ai_memory_open/blob/main/Model_Validation/generate-whitepaper.js"
click node_n24 "https://github.com/qosil/ai_memory_open/blob/main/zoho-mcp-server/src/index.js"
click node_n25 "https://github.com/qosil/ai_memory_open/blob/main/zoho-mcp-server/src/auth.js"
click node_n26 "https://github.com/qosil/ai_memory_open/tree/main/zoho-mcp-server/src/tools"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n2,node_n3,node_n4,node_n5,node_n6,node_n7,node_n8,node_n9,node_n20,node_n21 toneBlue
class node_n10,node_n11,node_n12,node_n13 toneAmber
class node_n14,node_n15,node_n16,node_n17 toneMint
class node_n18,node_n19 toneRose
class node_n22,node_n23 toneIndigo
class node_n24,node_n25,node_n26 toneTeal
class node_n1 toneNeutral
```

## Components

### Memory Core

Durable context, session continuity, and retrieval indexes.

- [Master Context](https://github.com/qosil/ai_memory_open/blob/main/Master-AI-Context.md): control-plane · Top-level always-read context for starting and steering work. · `Master-AI-Context.md`
- [Setup Guide](https://github.com/qosil/ai_memory_open/blob/main/setup-AI-Memory.md): bootstrap · Instructions for initializing the AI memory workflow. · `setup-AI-Memory.md`
- [Staging Flow](https://github.com/qosil/ai_memory_open/blob/main/staging.md): workflow · High-level staging and progression guide for work intake. · `staging.md`
- [Memory Init](https://github.com/qosil/ai_memory_open/blob/main/PROJECT_MEMORY_INIT.md): bootstrap · Project-memory initialization procedure and scaffolding. · `PROJECT_MEMORY_INIT.md`
- [Next Steps](https://github.com/qosil/ai_memory_open/blob/main/NextSteps.md): planning index · Active task queue and forward plan. · `NextSteps.md`
- [Key Decisions](https://github.com/qosil/ai_memory_open/blob/main/Key-Decisions.md): decision log · Persistent record of major choices and rationale. · `Key-Decisions.md`
- [Sessions](https://github.com/qosil/ai_memory_open/blob/main/Sessions.md): session log · Session continuity index and historical work trace. · `Sessions.md`
- [Risk Registry](https://github.com/qosil/ai_memory_open/blob/main/Risk-Registry.md): risk log · Persistent list of project and operating risks. · `Risk-Registry.md`
- [Memory Stores](https://github.com/qosil/ai_memory_open/tree/main/session-summary): durable memory · Persistent session summaries, decisions, and contact profiles. · `session-summary`
- [Contacts](https://github.com/qosil/ai_memory_open/tree/main/contacts): profile store · Structured contact and communication preference profiles. · `contacts`

### Governance

Operating standards, lifecycle rules, and control-plane docs.

- [Open/Close](https://github.com/qosil/ai_memory_open/blob/main/agents/open.md): lifecycle rules · Session boundary for loading context, working, and persisting results. · `agents/open.md`
- [Closure Rules](https://github.com/qosil/ai_memory_open/blob/main/agents/closure.md): lifecycle rules · Finalization and commit guidance for ending a session. · `agents/closure.md`
- [Standards](https://github.com/qosil/ai_memory_open/blob/HEAD/Standards%20and%20Policy/CCDE-Operating-Standard.md): policy layer · Operating standards and communication rules applied across work. · `Standards and Policy/CCDE-Operating-Standard.md`
- [Comm Standard](https://github.com/qosil/ai_memory_open/blob/HEAD/Standards%20and%20Policy/Communication-Standard.md): policy layer · Communication norms that constrain how the assistant interacts. · `Standards and Policy/Communication-Standard.md`

### Advisor Library

Reusable domain-specific reasoning modules.

- [Domain Agents](https://github.com/qosil/ai_memory_open/tree/main/Memory_Agents): advisor library · Catalog of reusable domain-specific reasoning modules. · `Memory_Agents`
- [Strategy](https://github.com/qosil/ai_memory_open/blob/main/Memory_Agents/Strategy/strategy-advisor.md): advisor pack · Strategic reasoning module within the advisor library. · `Memory_Agents/Strategy/strategy-advisor.md`
- [Operations](https://github.com/qosil/ai_memory_open/blob/main/Memory_Agents/Operations/operations-advisor.md): advisor pack · Operations reasoning module within the advisor library. · `Memory_Agents/Operations/operations-advisor.md`
- [Software Dev](https://github.com/qosil/ai_memory_open/blob/main/Memory_Agents/Software-Development/software-development-advisor.md): advisor pack · Software-development reasoning module within the advisor library. · `Memory_Agents/Software-Development/software-development-advisor.md`

### Project Workspaces

Where concrete projects are staged and initialized.

- [Projects](https://github.com/qosil/ai_memory_open/tree/main/projects): workspace root · Root area for concrete project instances and initialized workspaces. · `projects`
- [Staging Area](https://github.com/qosil/ai_memory_open/tree/main/projects/staging): project staging · Workspace for ideation and projects in planning. · `projects/staging`

### Validation

Methodology research and white-paper artifacts.

- [Validation Library](https://github.com/qosil/ai_memory_open/tree/main/Model_Validation): research base · White papers and methodology documents supporting the operating model. · `Model_Validation`
- [Whitepaper Gen](https://github.com/qosil/ai_memory_open/blob/main/Model_Validation/generate-whitepaper.js): document generator · Script that generates validation white papers. · `Model_Validation/generate-whitepaper.js`

### Zoho Connector

Node.js MCP server for external SaaS integrations.

- [Zoho MCP](https://github.com/qosil/ai_memory_open/blob/main/zoho-mcp-server/src/index.js): integration runtime · Node.js server exposing Zoho tools via MCP. · `zoho-mcp-server/src/index.js`
- [Auth Setup](https://github.com/qosil/ai_memory_open/blob/main/zoho-mcp-server/src/auth.js): integration auth · Zoho credential handling and authentication logic. · `zoho-mcp-server/src/auth.js`
- [Tool Modules](https://github.com/qosil/ai_memory_open/tree/main/zoho-mcp-server/src/tools): integration tools · Zoho domain tool implementations for external service access. · `zoho-mcp-server/src/tools`

### Other components

- **AI Assistant**: actor · Primary runtime that reads, writes, and resumes work from repo memory.

## Connections

- AI Assistant → Master Context: loads · Always reads core context before doing work.
- AI Assistant → Setup Guide: initializes · Uses setup instructions to establish the memory workflow.
- AI Assistant → Open/Close: opens · Starts each session through the open lifecycle boundary.
- AI Assistant → Closure Rules: closes · Finalizes work through the closure lifecycle boundary.
- Open/Close → Master Context: reads · Loads the always-read context during session open.
- Open/Close → Key Decisions: indexes · Pulls decision history as part of context loading.
- Open/Close → Sessions: indexes · Pulls session history for continuity.
- Open/Close → Risk Registry: indexes · Checks current risks during session open.
- AI Assistant → Next Steps: plans · Uses next steps as the active planning surface.
- AI Assistant → Standards: constrained by · Follows operating standards across all work.
- AI Assistant → Comm Standard: communicates by · Uses communication standards for interaction style.
- Domain Agents → Strategy: contains · Strategy advisor is one module in the library.
- Domain Agents → Operations: contains · Operations advisor is one module in the library.
- Domain Agents → Software Dev: contains · Software development advisor is one module in the library.
- AI Assistant → Domain Agents: deploys · Selects domain advisors on demand for specialized reasoning.
- AI Assistant → Projects: works in · Creates and updates project workspaces under projects/.
- Projects → Staging Area: starts in · New or planned work is staged here before project initialization.
- AI Assistant → Memory Stores: persists · Writes summaries and trace artifacts to durable memory stores.
- AI Assistant → Contacts: profiles · Records structured contact preferences and profiles.
- AI Assistant → Validation Library: studies · Uses validation materials to understand the methodology.
- Validation Library → Whitepaper Gen: generates · Whitepaper generation script supports the validation library.
- AI Assistant → Zoho MCP: invokes · May use the MCP server as the runtime integration boundary.
- Zoho MCP → Auth Setup: uses · Server relies on auth setup for Zoho access.
- Zoho MCP → Tool Modules: exposes · Tool modules implement Zoho service actions.
- Tool Modules → Zoho MCP: served by · Tool modules are loaded and served through the MCP runtime.
- Standards → Open/Close: governs · Standards shape how session open/close operates.
- Standards → AI Assistant: governs · Standards constrain assistant behavior.
- Projects → Memory Init: initialized by · Projects are created through the memory initialization procedure.
- Key Decisions → Sessions: cross-references · Decisions and sessions reference each other as durable memory.