# kdbhalala/agi-memory architecture

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

- Interactive diagram: https://gitdiagram.com/kdbhalala/agi-memory
- Repository: https://github.com/kdbhalala/agi-memory

## Overview

agi-memory is an on-device memory system for coding assistants. Assistants connect through the MCP server or lifecycle hooks; they record and retrieve project memories, session history, and code structure across tools. The four memory layers provide working, knowledge-graph, episodic, and structural-code capabilities, with promotion, summaries, import, and recall supporting the day-to-day workflow. The vault and sync modules provide durable, Git-friendly storage and optional cross-device synchronization. Edges reflect README statements and source-index references; unsampled implementation details are not assumed.

Main entry points: [`src/agi_memory/mcp_server.py`](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/mcp_server.py) (MCP server), [`src/agi_memory/layers/session_layer.py`](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/session_layer.py) (Working memory), [`src/agi_memory/hooks.py`](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/hooks.py) (Lifecycle hooks), [`src/agi_memory/vault.py`](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/vault.py) (Memory vault)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Assistant interfaces"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_hooks["Lifecycle hooks<br/>[hooks.py]"]
  node_integrate["Assistant integration<br/>[integrate.py]"]
end

subgraph group_memory["Memory layers"]
  node_working["Working memory<br/>[session_layer.py]"]
  node_knowledge["Knowledge graph<br/>[graph_layer.py]"]
  node_episodic["Episodic history<br/>[episodic_layer.py]"]
  node_codeindex["Code graph<br/>[code_layer.py]"]
  node_layerbase["Layer primitives<br/>[base.py]"]
  node_recall["Recall<br/>[recall.py]"]
  node_promote["Memory promotion<br/>[promote.py]"]
end

subgraph group_history["History and analysis"]
  node_historyimport["History import<br/>[history_import.py]"]
  node_summarizer["Session summaries<br/>[summarizer.py]"]
  node_analyze["Code analysis<br/>[analyze.py]"]
  node_redact["Credential redaction<br/>[redact.py]"]
end

subgraph group_persistence["Storage and sync"]
  node_vault[("Memory vault<br/>[vault.py]")]
  node_sync["Git synchronization<br/>[sync.py]"]
end

subgraph group_operations["Setup and utilities"]
  node_config["Path configuration<br/>[config.py]"]
  node_bootstrap["Memory bootstrap<br/>[bootstrap.py]"]
  node_audit["Memory audit<br/>[audit.py]"]
  node_tui["Interactive dashboard<br/>[tui.py]"]
end

node_assistant(("Coding assistant"))

node_assistant -->|"uses tools"| node_mcp
node_assistant -->|"triggers events"| node_hooks
node_integrate -->|"configures server"| node_mcp
node_integrate -->|"installs hooks"| node_hooks
node_mcp -->|"records and recalls"| node_working
node_mcp -->|"records durable facts"| node_knowledge
node_mcp -->|"serves timelines"| node_episodic
node_mcp -->|"serves code queries"| node_codeindex
node_mcp -->|"delegates recall"| node_recall
node_mcp -->|"delegates promotion"| node_promote
node_hooks -->|"tracks sessions"| node_episodic
node_hooks -->|"injects memories"| node_working
node_hooks -->|"requests sync"| node_sync
node_historyimport -->|"imports sessions"| node_episodic
node_historyimport -->|"redacts imported text"| node_redact
node_historyimport -->|"indexes recent history"| node_working
node_summarizer -->|"writes rollups"| node_episodic
node_summarizer -->|"redacts summaries"| node_redact
node_analyze -->|"uses initialized state"| node_bootstrap
node_analyze -->|"resolves settings"| node_config
node_working -->|"opens database"| node_layerbase
node_episodic -->|"opens database"| node_layerbase
node_knowledge -->|"opens database"| node_layerbase
node_codeindex -->|"opens database"| node_layerbase
node_vault -->|"exports and imports records"| node_working
node_vault -->|"exports and imports graph"| node_knowledge
node_sync -->|"exports vault data"| node_vault
node_sync -.->|"syncs via Git remote"| node_assistant
node_bootstrap -->|"resolves paths"| node_config
node_bootstrap -->|"imports history"| node_historyimport
node_audit -->|"checks memory records"| node_working
node_audit -->|"checks vault state"| node_vault
node_tui -->|"shows audit results"| node_audit
node_tui -->|"shows vault data"| node_vault

click node_mcp "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/mcp_server.py"
click node_hooks "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/hooks.py"
click node_integrate "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/integrate.py"
click node_working "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/session_layer.py"
click node_knowledge "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/graph_layer.py"
click node_episodic "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/episodic_layer.py"
click node_codeindex "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/code_layer.py"
click node_layerbase "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/base.py"
click node_recall "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/recall.py"
click node_promote "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/promote.py"
click node_historyimport "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/history_import.py"
click node_summarizer "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/summarizer.py"
click node_analyze "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/analyze.py"
click node_redact "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/redact.py"
click node_vault "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/vault.py"
click node_sync "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/sync.py"
click node_config "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/config.py"
click node_bootstrap "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/bootstrap.py"
click node_audit "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/audit.py"
click node_tui "https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/tui.py"

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_mcp,node_hooks,node_integrate toneBlue
class node_working,node_knowledge,node_episodic,node_codeindex,node_layerbase,node_recall,node_promote toneAmber
class node_historyimport,node_summarizer,node_analyze,node_redact toneMint
class node_vault,node_sync toneRose
class node_config,node_bootstrap,node_audit,node_tui,node_assistant toneIndigo
```

## Components

### Assistant interfaces

- [MCP server](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/mcp_server.py): `src/agi_memory/mcp_server.py`
- [Lifecycle hooks](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/hooks.py): `src/agi_memory/hooks.py`
- [Assistant integration](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/integrate.py): `src/agi_memory/integrate.py`

### Memory layers

- [Working memory](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/session_layer.py): `src/agi_memory/layers/session_layer.py`
- [Knowledge graph](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/graph_layer.py): `src/agi_memory/layers/graph_layer.py`
- [Episodic history](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/episodic_layer.py): `src/agi_memory/layers/episodic_layer.py`
- [Code graph](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/code_layer.py): `src/agi_memory/layers/code_layer.py`
- [Layer primitives](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/layers/base.py): `src/agi_memory/layers/base.py`
- [Recall](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/recall.py): `src/agi_memory/recall.py`
- [Memory promotion](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/promote.py): `src/agi_memory/promote.py`

### History and analysis

- [History import](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/history_import.py): `src/agi_memory/history_import.py`
- [Session summaries](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/summarizer.py): `src/agi_memory/summarizer.py`
- [Code analysis](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/analyze.py): `src/agi_memory/analyze.py`
- [Credential redaction](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/redact.py): `src/agi_memory/redact.py`

### Storage and sync

- [Memory vault](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/vault.py): `src/agi_memory/vault.py`
- [Git synchronization](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/sync.py): `src/agi_memory/sync.py`

### Setup and utilities

- [Path configuration](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/config.py): `src/agi_memory/config.py`
- [Memory bootstrap](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/bootstrap.py): `src/agi_memory/bootstrap.py`
- [Memory audit](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/audit.py): `src/agi_memory/audit.py`
- [Interactive dashboard](https://github.com/kdbhalala/agi-memory/blob/main/src/agi_memory/tui.py): `src/agi_memory/tui.py`

### Other components

- **Coding assistant**

## Connections

- Coding assistant → MCP server: uses tools (evidence: `README.md`)
- Coding assistant → Lifecycle hooks: triggers events (evidence: `README.md`)
- Assistant integration → MCP server: configures server (evidence: `src/agi_memory/integrate.py`)
- Assistant integration → Lifecycle hooks: installs hooks (evidence: `src/agi_memory/integrate.py`)
- MCP server → Working memory: records and recalls (evidence: `src/agi_memory/mcp_server.py`)
- MCP server → Knowledge graph: records durable facts (evidence: `src/agi_memory/mcp_server.py`)
- MCP server → Episodic history: serves timelines (evidence: `src/agi_memory/mcp_server.py`)
- MCP server → Code graph: serves code queries (evidence: `src/agi_memory/mcp_server.py`)
- MCP server → Recall: delegates recall (evidence: `src/agi_memory/mcp_server.py`)
- MCP server → Memory promotion: delegates promotion (evidence: `src/agi_memory/mcp_server.py`)
- Lifecycle hooks → Episodic history: tracks sessions (evidence: `src/agi_memory/hooks.py`)
- Lifecycle hooks → Working memory: injects memories (evidence: `src/agi_memory/hooks.py`)
- Lifecycle hooks → Git synchronization: requests sync (evidence: `src/agi_memory/hooks.py`)
- History import → Episodic history: imports sessions (evidence: `src/agi_memory/history_import.py`)
- History import → Credential redaction: redacts imported text (evidence: `src/agi_memory/history_import.py`)
- History import → Working memory: indexes recent history (evidence: `README.md`)
- Session summaries → Episodic history: writes rollups (evidence: `src/agi_memory/summarizer.py`)
- Session summaries → Credential redaction: redacts summaries (evidence: `src/agi_memory/summarizer.py`)
- Code analysis → Memory bootstrap: uses initialized state (evidence: `src/agi_memory/analyze.py`)
- Code analysis → Path configuration: resolves settings (evidence: `src/agi_memory/analyze.py`)
- Working memory → Layer primitives: opens database (evidence: `src/agi_memory/layers/session_layer.py`)
- Episodic history → Layer primitives: opens database (evidence: `src/agi_memory/layers/episodic_layer.py`)
- Knowledge graph → Layer primitives: opens database (evidence: `src/agi_memory/layers/graph_layer.py`)
- Code graph → Layer primitives: opens database (evidence: `src/agi_memory/layers/code_layer.py`)
- Memory vault → Working memory: exports and imports records (evidence: `src/agi_memory/vault.py`)
- Memory vault → Knowledge graph: exports and imports graph (evidence: `src/agi_memory/vault.py`)
- Git synchronization → Memory vault: exports vault data (evidence: `src/agi_memory/sync.py`)
- Git synchronization → Coding assistant: syncs via Git remote (evidence: `README.md`)
- Memory bootstrap → Path configuration: resolves paths (evidence: `src/agi_memory/bootstrap.py`)
- Memory bootstrap → History import: imports history (evidence: `src/agi_memory/bootstrap.py`)
- Memory audit → Working memory: checks memory records (evidence: `src/agi_memory/audit.py`)
- Memory audit → Memory vault: checks vault state (evidence: `src/agi_memory/audit.py`)
- Interactive dashboard → Memory audit: shows audit results (evidence: `src/agi_memory/tui.py`)
- Interactive dashboard → Memory vault: shows vault data (evidence: `src/agi_memory/tui.py`)
