Persistent Agent Memory
Relevant source files
The following files were used as context for generating this wiki page:
Persistent Agent Memory is a core feature of the Memory Context Browser (MCB) that enables AI agents to maintain state across different sessions. It allows for the storage of observations, timeline tracking, and context injection, facilitating a deeper understanding of the codebase and project history over time. This system is built upon the Model Context Protocol (MCP) to provide a standardized way for agents to interact with long-term memory structures.
Sources: README.md:12-14, AGENTS.md:162-164
Architecture and Components
The memory system is organized following Clean Architecture principles, ensuring that business logic remains decoupled from infrastructure concerns. The memory components are distributed across the mcb-domain, mcb-infrastructure, and mcb-server crates.
Core Entities
The domain layer defines the fundamental building blocks of the memory system, primarily focused on sessions and observations.
- Observation: Represents a discrete piece of information or insight gained by the agent during operation.
- AgentSession: Tracks the lifecycle of an agent's interaction, providing context for stored memories.
- Timeline: A chronological view of observations and events within or across sessions.
Sources: crates/mcb-domain/src/entities/mod.rs:43-51, crates/mcb-domain/src/lib.rs:56-61
Data Flow for Memory Storage
When an agent stores a memory, the request flows through the MCP server layer, validates provenance, and eventually reaches the infrastructure layer for persistence in a vector store or relational database.
The diagram shows the standard flow from a tool call to final persistence.
Sources: crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:136-150, README.md:92-105
MCP Tool Interface
The memory system is exposed to agents through a specific family of MCP tools. These tools allow for CRUD operations on memories and sessions, as well as complex retrieval like timeline generation.
Public Memory Tools
| Tool Name | Description |
|---|---|
store_memory | Persists a new observation or fact into the long-term memory. |
get_memories | Retrieves specific memories based on IDs or criteria. |
list_memories | Lists available memories with filtering options. |
memory_timeline | Generates a chronological view of stored agent activities. |
inject_context | Injects relevant memories directly into the agent's current prompt context. |
Sources: README.md:83-85, crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:32-55
Session Management Tools
| Tool Name | Description |
|---|---|
start_session | Initializes a new tracking session for an agent task. |
get_session | Retrieves details about a specific active or historical session. |
list_sessions | Lists sessions associated with the current project or agent. |
summarize_session | Generates a high-level summary of activities within a session. |
Sources: README.md:86-87, crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:32-55
Security and Provenance
Memory operations are protected by a "Provenance Gate." Every tool call that interacts with the data plane (like store_memory or search_memory) must provide execution provenance.
This sequence ensures that memories are always associated with a valid session, repository, and operator.
Sources: crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:136-168
Mandatory Provenance Fields
The server rejects memory operations if the following fields are missing from the ToolExecutionContext:
session_id: The unique identifier for the current agent session.repo_id: The repository context for the memory.operator_id: The user or entity initiating the action.delegated: Boolean indicating if the agent is operating on behalf of another.timestamp: The exact time the observation occurred.
Sources: crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:149-158
Implementation Details
The memory system leverages linkme for distributed service registration, allowing different providers (e.g., SQLite for metadata, Milvus for semantic search) to be plugged into the domain ports.
// Example of how memory entities are defined in the domain
pub mod memory {
pub use super::observation::Observation;
}
pub mod agent {
pub struct AgentSession {
pub id: String,
pub status: AgentSessionStatus,
// ... other fields
}
}
Sources: crates/mcb-domain/src/entities/mod.rs:10-51, crates/mcb-domain/src/lib.rs:56-65
Persistent Agent Memory ensures that the AI agent does not "forget" critical project decisions or architectural constraints between restarts, effectively creating a continuously evolving knowledge base for the project.