Cross-Session Memory Management

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• CLAUDE_ONBOARDING.md
• init-project.sh
• scripts/artifact_index.py
• scripts/artifact_schema.sql
• install-global.sh
• tests/test_artifact_index.py

Cross-Session Memory Management in the Continuous Claude system is a robust framework designed to overcome the lossy nature of context compaction in long-running AI sessions. Instead of relying on the LLM's internal summaries, the system preserves state with high fidelity across /clear operations by utilizing external markdown "ledgers," permanent handoff documents, and a local SQLite-based "Context Graph" search index.

This system ensures that reasoning, decisions, and task progress remain available to the agent even after the conversation history is wiped. It operates 100% offline, prioritizing local storage and local alternatives to cloud services like Braintrust.

Sources: CLAUDE_ONBOARDING.md:10-22, CLAUDE.md:237-238

Core Continuity Mechanisms

The system employs three primary levels of state preservation to maintain context across sessions.

1. Continuity Ledgers

Ledgers are ephemeral snapshots of the current session state. They track what has been completed, what is currently being worked on, and what the next steps are. Before a user executes a /clear command, they use the /continuity_ledger skill to update this file.

2. Handoff Documents

Handoffs are permanent records of completed tasks. They include post-mortems detailing what worked, what failed, and key decisions made during the implementation of a specific task number within a session.

3. Implementation Plans

Implementation plans are design documents that outline the approach and phases for a feature. These are tracked in the thoughts/shared/plans/ directory and serve as the source of truth for implementation verification.

Sources: CLAUDE_ONBOARDING.md:24-34, scripts/artifact_index.py:165-175

System Architecture

The memory management architecture consists of five layers, primarily facilitated by the claude-mem plugin and the local artifact index.

Component Details

Component	Responsibility	Source File
Hooks Layer	Injects context at start; captures observations and summaries.	CLAUDE.md:155-160
Worker Service	Bun-managed Express API on port 37777.	CLAUDE.md:162-163
MCP Server	Provides the mcp-search interface to the agent.	CLAUDE.md:165-166
Service Layer	Manages session state, search managers, and vector sync.	CLAUDE.md:168-172
Data Layer	Persistent storage in ~/.claude-mem/ (SQLite and Chroma).	CLAUDE.md:174-177

Context Graph & Artifact Indexing

The Context Graph is a local search index used to query session artifacts using Full-Text Search (FTS5).

Database Schema

The system uses a SQLite database located at .claude/cache/artifact-index/context.db. It features dedicated tables for handoffs, plans, continuity snapshots, and learning-based queries.

Indexing Process

The artifact_index.py script parses markdown files into structured data for the SQLite tables. It supports both bulk indexing of entire directories and single-file indexing triggered by session hooks.

# scripts/artifact_index.py:313-330
def index_single_file(conn: sqlite3.Connection, file_path: Path) -> bool:
    """Index a single file based on its location/type."""
    file_path = Path(file_path).resolve()
    path_str = str(file_path)

    if "handoffs" in path_str and file_path.suffix == ".md":
        data = parse_handoff(file_path)
        # ... Insert logic ...
    elif "plans" in path_str and file_path.suffix == ".md":
        data = parse_plan(file_path)
        # ... Insert logic ...

Sources: scripts/artifact_index.py:313-330, tests/test_artifact_index.py:284-300

Project Initialization and Lifecycle

A new project must be initialized to support cross-session memory. This setup creates the necessary directory structure and initializes the local database.

Workflow: Session Lifecycle

Storage Locations

The init-project.sh script sets up the following directory structure for memory management:

• thoughts/ledgers/: Session state snapshots (tracked in Git).
• thoughts/shared/handoffs/: Task-level post-mortems (tracked in Git).
• thoughts/shared/plans/: Design documents (tracked in Git).
• .claude/cache/artifact-index/context.db: Local search index (Git ignored).

Sources: init-project.sh:110-125, init-project.sh:196-205

Search and Retrieval

The agent interacts with cross-session memory through specific MCP tools and skills.

Tool/Command	Purpose	Token Efficiency
mcp__plugin_claude-mem_claude-mem-search__search	General search across past sessions.	~50 tokens/result
mcp__plugin_claude-mem_claude-mem-search__timeline	Retrieve chronological context for a project.	~100 tokens/result
mcp__plugin_claude-mem_claude-mem-search__get_observations	Detailed lookup of specific tool outputs.	~500 tokens/result
/mem-search	High-level skill for memory retrieval.	N/A

Sources: CLAUDE.md:183-199, CLAUDE_ONBOARDING.md:75-76

Summary

Cross-Session Memory Management provides a persistent "brain" for Claude within a project. By combining markdown-based documentation (ledgers and handoffs) with a local, searchable SQLite index (Context Graph), the system ensures that long-term project knowledge and architectural decisions are never lost to context window limitations or session resets. The framework operates entirely locally, maintaining privacy and performance without requiring external API dependencies.