# tigerless-labs/agent-memory architecture

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

- Interactive diagram: https://gitdiagram.com/tigerless-labs/agent-memory
- Repository: https://github.com/tigerless-labs/agent-memory

## Overview

agent-memory is a long-term memory runtime for AI agents: hosts capture session material, distill it into durable memories, and retrieve ranked paths that agents can inspect at increasing depth. Markdown files are authoritative; SQLite and retrieval indexes are rebuildable projections. Separate interfaces include the CLI, MCP, and host adapters. A scheduled Manage pass consolidates memories and can use host or endpoint reasoning. The README documents the broader capabilities; edges relying on source are limited to indexed references and the excerpts shown, so unsampled wiring is omitted.

Main entry points: [`packages/core/src/agent_memory/core/store.py`](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/store.py) (Memory store), [`packages/executor/src/agent_memory/executor/reasoners.py`](https://github.com/tigerless-labs/agent-memory/blob/main/packages/executor/src/agent_memory/executor/reasoners.py) (Reasoner providers), [`packages/mcp/src/agent_memory/mcp/server.py`](https://github.com/tigerless-labs/agent-memory/blob/main/packages/mcp/src/agent_memory/mcp/server.py) (MCP server), [`packages/core/src/agent_memory/core/distill.py`](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/distill.py) (Distillation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_mcp["MCP server<br/>[server.py]"]
  node_mcp_tools["MCP tools<br/>[tools.py]"]
  node_adapters["Host adapters"]
end

subgraph group_capture["Capture and distillation"]
  node_capture_flow["Session capture<br/>[observation.py]"]
  node_sessions["Session archive<br/>[sessions.py]"]
  node_distill["Distillation<br/>[distill.py]"]
  node_prompts["Agent prompts<br/>[prompts.py]"]
end

subgraph group_memory["Memory and retrieval"]
  node_store["Memory store<br/>[store.py]"]
  node_memory_files["Markdown memories"]
  node_index["Search index<br/>[search_index.py]"]
  node_database[("SQLite cache<br/>[database.py]")]
  node_recall["Ranked recall<br/>[recall.py]"]
  node_context["Context assembly<br/>[context.py]"]
  node_injection["Session injection<br/>[injection.py]"]
end

subgraph group_manage["Sleep-time management"]
  node_manage["Manage sleep<br/>[manage.py]"]
  node_reasoning["Review reasoning<br/>[reasoning.py]"]
end

subgraph group_execution["Host execution"]
  node_executor["Host drivers<br/>[hosts.py]"]
  node_reasoners["Reasoner providers<br/>[reasoners.py]"]
end

node_agent(("Agent host"))
node_endpoint(("Model endpoint"))

node_agent -->|"runs commands"| node_cli
node_agent -->|"calls tools"| node_mcp
node_cli -->|"uses"| node_store
node_mcp -->|"dispatches"| node_mcp_tools
node_mcp -->|"opens"| node_store
node_mcp_tools -->|"uses"| node_store
node_agent -->|"invokes hooks"| node_adapters
node_adapters -.->|"captures"| node_capture_flow
node_capture_flow -.->|"archives traces"| node_sessions
node_distill -->|"uses instructions"| node_prompts
node_distill -->|"writes memories"| node_store
node_store -->|"writes files"| node_memory_files
node_store -->|"projects records"| node_index
node_index -->|"updates cache"| node_database
node_recall -.->|"queries index"| node_database
node_context -->|"retrieves"| node_recall
node_context -->|"reads files"| node_store
node_agent -->|"reads directly"| node_memory_files
node_agent -.->|"receives index"| node_injection
node_manage -->|"consolidates"| node_store
node_manage -->|"requests review"| node_reasoning
node_reasoners -->|"implements review"| node_reasoning
node_reasoners -->|"runs host"| node_executor
node_reasoners -->|"calls endpoint"| node_endpoint

click node_cli "https://github.com/tigerless-labs/agent-memory/blob/main/packages/cli/src/agent_memory/cli/main.py"
click node_mcp "https://github.com/tigerless-labs/agent-memory/blob/main/packages/mcp/src/agent_memory/mcp/server.py"
click node_mcp_tools "https://github.com/tigerless-labs/agent-memory/blob/main/packages/mcp/src/agent_memory/mcp/tools.py"
click node_adapters "https://github.com/tigerless-labs/agent-memory/tree/main/packages/adapters/src/agent_memory/adapters"
click node_capture_flow "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/observation.py"
click node_sessions "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/sessions.py"
click node_distill "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/distill.py"
click node_prompts "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/prompts.py"
click node_store "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/store.py"
click node_index "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/search_index.py"
click node_database "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/database.py"
click node_recall "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/recall.py"
click node_context "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/context.py"
click node_injection "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/injection.py"
click node_manage "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/manage.py"
click node_reasoning "https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/reasoning.py"
click node_executor "https://github.com/tigerless-labs/agent-memory/blob/main/packages/executor/src/agent_memory/executor/hosts.py"
click node_reasoners "https://github.com/tigerless-labs/agent-memory/blob/main/packages/executor/src/agent_memory/executor/reasoners.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_cli,node_mcp,node_mcp_tools,node_adapters toneBlue
class node_capture_flow,node_sessions,node_distill,node_prompts toneAmber
class node_store,node_memory_files,node_index,node_database,node_recall,node_context,node_injection toneMint
class node_manage,node_reasoning toneRose
class node_executor,node_reasoners,node_agent,node_endpoint toneIndigo
```

## Components

### Agent interfaces

- [CLI](https://github.com/tigerless-labs/agent-memory/blob/main/packages/cli/src/agent_memory/cli/main.py): `packages/cli/src/agent_memory/cli/main.py`
- [MCP server](https://github.com/tigerless-labs/agent-memory/blob/main/packages/mcp/src/agent_memory/mcp/server.py): `packages/mcp/src/agent_memory/mcp/server.py`
- [MCP tools](https://github.com/tigerless-labs/agent-memory/blob/main/packages/mcp/src/agent_memory/mcp/tools.py): `packages/mcp/src/agent_memory/mcp/tools.py`
- [Host adapters](https://github.com/tigerless-labs/agent-memory/tree/main/packages/adapters/src/agent_memory/adapters): `packages/adapters/src/agent_memory/adapters`

### Capture and distillation

- [Session capture](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/observation.py): `packages/core/src/agent_memory/core/observation.py`
- [Session archive](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/sessions.py): `packages/core/src/agent_memory/core/sessions.py`
- [Distillation](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/distill.py): `packages/core/src/agent_memory/core/distill.py`
- [Agent prompts](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/prompts.py): `packages/core/src/agent_memory/core/prompts.py`

### Memory and retrieval

- [Memory store](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/store.py): `packages/core/src/agent_memory/core/store.py`
- **Markdown memories**
- [Search index](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/search_index.py): `packages/core/src/agent_memory/core/search_index.py`
- [SQLite cache](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/database.py): `packages/core/src/agent_memory/core/database.py`
- [Ranked recall](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/recall.py): `packages/core/src/agent_memory/core/recall.py`
- [Context assembly](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/context.py): `packages/core/src/agent_memory/core/context.py`
- [Session injection](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/injection.py): `packages/core/src/agent_memory/core/injection.py`

### Sleep-time management

- [Manage sleep](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/manage.py): `packages/core/src/agent_memory/core/manage.py`
- [Review reasoning](https://github.com/tigerless-labs/agent-memory/blob/main/packages/core/src/agent_memory/core/reasoning.py): `packages/core/src/agent_memory/core/reasoning.py`

### Host execution

- [Host drivers](https://github.com/tigerless-labs/agent-memory/blob/main/packages/executor/src/agent_memory/executor/hosts.py): `packages/executor/src/agent_memory/executor/hosts.py`
- [Reasoner providers](https://github.com/tigerless-labs/agent-memory/blob/main/packages/executor/src/agent_memory/executor/reasoners.py): `packages/executor/src/agent_memory/executor/reasoners.py`

### Other components

- **Agent host**
- **Model endpoint**

## Connections

- Agent host → CLI: runs commands
- Agent host → MCP server: calls tools
- CLI → Memory store: uses (evidence: `packages/cli/src/agent_memory/cli/main.py`)
- MCP server → MCP tools: dispatches (evidence: `packages/mcp/src/agent_memory/mcp/server.py`)
- MCP server → Memory store: opens (evidence: `packages/mcp/src/agent_memory/mcp/server.py`)
- MCP tools → Memory store: uses (evidence: `packages/mcp/src/agent_memory/mcp/tools.py`)
- Agent host → Host adapters: invokes hooks
- Host adapters → Session capture: captures
- Session capture → Session archive: archives traces
- Distillation → Agent prompts: uses instructions (evidence: `packages/core/src/agent_memory/core/distill.py`)
- Distillation → Memory store: writes memories (evidence: `packages/core/src/agent_memory/core/distill.py`)
- Memory store → Markdown memories: writes files
- Memory store → Search index: projects records (evidence: `packages/core/src/agent_memory/core/store.py`)
- Search index → SQLite cache: updates cache (evidence: `packages/core/src/agent_memory/core/search_index.py`)
- Ranked recall → SQLite cache: queries index (evidence: `packages/core/src/agent_memory/core/recall.py`)
- Context assembly → Ranked recall: retrieves (evidence: `packages/core/src/agent_memory/core/context.py`)
- Context assembly → Memory store: reads files (evidence: `packages/core/src/agent_memory/core/context.py`)
- Agent host → Markdown memories: reads directly
- Agent host → Session injection: receives index
- Manage sleep → Memory store: consolidates (evidence: `packages/core/src/agent_memory/core/manage.py`)
- Manage sleep → Review reasoning: requests review (evidence: `packages/core/src/agent_memory/core/manage.py`)
- Reasoner providers → Review reasoning: implements review (evidence: `packages/executor/src/agent_memory/executor/reasoners.py`)
- Reasoner providers → Host drivers: runs host (evidence: `packages/executor/src/agent_memory/executor/reasoners.py`)
- Reasoner providers → Model endpoint: calls endpoint (evidence: `packages/executor/src/agent_memory/executor/reasoners.py`)