How tigerless-labs/agent-memory works
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: store.py Memory store · reasoners.py Reasoner providers · server.py MCP server · distill.py Distillation
Components 21
Agent interfaces
- CLI
packages/cli/src/agent_memory/cli/main.py - MCP server
packages/mcp/src/agent_memory/mcp/server.py - MCP tools
packages/mcp/src/agent_memory/mcp/tools.py - Host adapters
packages/adapters/src/agent_memory/adapters
Capture and distillation
- Session capture
packages/core/src/agent_memory/core/observation.py - Session archive
packages/core/src/agent_memory/core/sessions.py - Distillation
packages/core/src/agent_memory/core/distill.py - Agent prompts
packages/core/src/agent_memory/core/prompts.py
Memory and retrieval
- Memory store
packages/core/src/agent_memory/core/store.py - Markdown memories
- Search index
packages/core/src/agent_memory/core/search_index.py - SQLite cache
packages/core/src/agent_memory/core/database.py - Ranked recall
packages/core/src/agent_memory/core/recall.py - Context assembly
packages/core/src/agent_memory/core/context.py - Session injection
packages/core/src/agent_memory/core/injection.py
Sleep-time management
- Manage sleep
packages/core/src/agent_memory/core/manage.py - Review reasoning
packages/core/src/agent_memory/core/reasoning.py
Host execution
- Host drivers
packages/executor/src/agent_memory/executor/hosts.py - Reasoner providers
packages/executor/src/agent_memory/executor/reasoners.py
Other components
- Agent host
- Model endpoint
Connections 24
- Agent host → CLI: runs commands
- Agent host → MCP server: calls tools
- CLI → Memory store: uses
packages/cli/src/agent_memory/cli/main.py - MCP server → MCP tools: dispatches
packages/mcp/src/agent_memory/mcp/server.py - MCP server → Memory store: opens
packages/mcp/src/agent_memory/mcp/server.py - MCP tools → Memory store: uses
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
packages/core/src/agent_memory/core/distill.py - Distillation → Memory store: writes memories
packages/core/src/agent_memory/core/distill.py - Memory store → Markdown memories: writes files
- Memory store → Search index: projects records
packages/core/src/agent_memory/core/store.py - Search index → SQLite cache: updates cache
packages/core/src/agent_memory/core/search_index.py - Ranked recall → SQLite cache: queries index
packages/core/src/agent_memory/core/recall.py - Context assembly → Ranked recall: retrieves
packages/core/src/agent_memory/core/context.py - Context assembly → Memory store: reads files
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
packages/core/src/agent_memory/core/manage.py - Manage sleep → Review reasoning: requests review
packages/core/src/agent_memory/core/manage.py - Reasoner providers → Review reasoning: implements review
packages/executor/src/agent_memory/executor/reasoners.py - Reasoner providers → Host drivers: runs host
packages/executor/src/agent_memory/executor/reasoners.py - Reasoner providers → Model endpoint: calls endpoint
packages/executor/src/agent_memory/executor/reasoners.py