Persistent Memory & Sessions
Relevant source files
The following files were used as context for generating this wiki page:
Persistent Memory and Sessions in MCB (Memory Context Browser) provide a high-performance system for AI coding agents to maintain cross-session observation storage, timeline tracking, and context injection. This system allows agents to store and retrieve structured knowledge, such as topics, decisions, and next steps, ensuring continuity across different interactions.
The architecture follows Clean Architecture principles, separating the protocol handlers in mcb-server from the core business logic and port traits in mcb-domain. Memory is indexed semantically, allowing for natural language queries over indexed codebases and session histories.
Sources: README.md:10-15, AGENTS.md:143-154, crates/mcb-domain/src/entities/mod.rs:38-40
Architecture and Data Flow
The memory and session system is structured into families of operations that handle the storage, retrieval, and summarization of agent interactions. The flow typically starts with a tool call from an MCP client, which is processed by the server handlers and persisted through infrastructure services.
Memory & Session Tool Families
| Family | Key Tools | Description |
|---|---|---|
| Memory | store_memory, get_memories, memory_timeline | Stores and retrieves cross-session observations and context. |
| Session | start_session, summarize_session, list_sessions | Manages agent session lifecycles and generates summaries. |
| Agent | log_tool_call, log_delegation | Tracks specific actions and delegations within a session. |
Sources: README.md:52-60, AGENTS.md:195-204
Data Flow for Session Summarization
When an agent summarizes a session, the system extracts data such as topics and decisions, resolves the origin context (linking it to organizations and projects), and persists it via the MemoryServiceInterface.
The diagram shows the logic path for handling session summaries, branching between creation and retrieval based on input arguments.
Sources: crates/mcb-server/src/handlers/session/summarize.rs:18-30, crates/mcb-server/src/handlers/memory/session.rs:88-112
Core Data Structures
The system uses specific payload structures to ensure consistent data exchange between the MCP protocol and the internal domain entities.
SessionSummaryPayload
This structure captures the technical and contextual metadata of a session summary.
| Field | Type | Description |
|---|---|---|
session_id | Option<String> | Unique identifier for the session. |
topics | Vec<String> | High-level subjects discussed. |
decisions | Vec<String> | Specific choices made during the session. |
next_steps | Vec<String> | Actions to be taken following the session. |
key_files | Vec<String> | Files relevant to the session context. |
project_id | Option<String> | The associated project identifier. |
Sources: crates/mcb-server/src/handlers/memory/session.rs:17-34
Origin Context Resolution
The resolve_origin_context function is critical for maintaining data integrity and multi-tenancy. It maps incoming arguments (like org_id and repo_id) and payload fields (like worktree_id and model_id) to a canonical OriginContext entity.
// crates/mcb-server/src/handlers/memory/session.rs:37-56
fn resolve_session_origin_context(
args: &MemoryArgs,
payload: &SessionSummaryPayload,
session_id: &str,
) -> Result<OriginContext, McpError> {
resolve_origin_context(&OriginContextInput {
org_id: args.org_id.as_deref(),
project_id_args: args.project_id.as_deref(),
project_id_payload: payload.project_id.as_deref(),
session_from_args: Some(session_id),
// ... other mapping fields
require_project_id: true,
..Default::default()
})
}
Sources: crates/mcb-server/src/handlers/memory/session.rs:37-56
Implementation Details
Handler Logic
Handlers in mcb-server act as the entry points for MCP tools. They validate input arguments and interface with the domain services. For example, store_session ensures that the project_id is present in the resolved context before proceeding with persistence.
The sequence diagram illustrates the internal validation and service calls performed during session summarization.
Sources: crates/mcb-server/src/handlers/memory/session.rs:64-112, crates/mcb-server/src/handlers/session/summarize.rs:35-71
Error Handling
The system uses contextual error mapping to transform domain errors into protocol-compliant McpError responses. Common checks include verifying that data payloads are not missing and that required fields like content or session_id are present.
Sources: crates/mcb-server/tests/integration/error_shape_tests.rs:136-168, crates/mcb-server/src/handlers/memory/session.rs:82-87
Summary
Persistent Memory & Sessions form the backbone of agent continuity in MCB. By combining structured session summaries with semantic memory storage, the system enables agents to maintain complex state across multiple tasks. The implementation ensures strict architectural boundaries, with mcb-server managing the MCP communication and mcb-domain defining the core entities like AgentSession, Observation, and OriginContext.
Sources: crates/mcb-domain/src/entities/mod.rs:10-40, README.md:12-18