Cross-Session Memory

Continuity infrastructure for AI coding agents

Persistent memory, operational state, re-entry, context governance, and durable lessons across sessions, projects, and model changes.

Quick start · Codex setup · Feature map · Architecture · Privacy · Troubleshooting · Documentation · Contributing

---

CSM is not a chat-history dump or a thin vector-store wrapper. It is a continuity runtime that records what happened, retrieves what matters, reconstructs working state, and tells a new agent how to continue safely.

Why CSM exists

Coding agents are effective inside one context window and unreliable across many of them. Important decisions disappear into old transcripts, project state drifts, mistakes repeat, and every fresh session spends tokens rebuilding a partial understanding of the work.

CSM turns continuity into infrastructure.

Failure mode	CSM response
Fresh-session amnesia	Turn-1 AgentBook state and structured re-entry
Long-session context pressure	Compaction, context budgeting, checkpoints, and cached context
Repeated mistakes	Durable lessons, experience packets, and failure evidence
Weak retrieval	Hybrid vector, full-text, entity, type, tag, and importance signals
Unverifiable memory	Provenance, quality scoring, governance reports, and source attribution
Project-state drift	Append-only operational events, rolling summaries, and current-state projection
Storage lock-in	Full PostgreSQL path plus a local SQLite core mode

At a glance

Surface	Current implementation
Runtime tools	Up to 50 registered tool surfaces in the full PostgreSQL path
Persistence	PostgreSQL 14/16 and SQLite core mode
Verification	More than 1,500 automated tests, type checking, lint gates, CI matrix, and backup/restore drill
Session continuity	AgentBook front page plus layered re-entry and onboarding
Recall	Vector, text, entity, relationship, and fallback retrieval paths
Internal state	Experience packets, self-model, belief knowledge, and advisory context
Governance	Deduplication, merge/supersede, archive candidates, quality reports, and continuity health
Host	OpenCode plugin plus a packaged Codex MCP command and installable PostgreSQL Codex plugin

Capability map

System	What it provides
Memory engine	Durable memories, lessons, transcripts, hybrid search, related-memory traversal, distillation, and embedding backfill
AgentBook	Append-only project events, rolling summaries, explicit rules, current-state projection, and a turn-1 front page
Re-entry and onboarding	Identity, project state, constraints, goals, checkpoints, relevant memories, advisories, and source-aware injection
Context control	Token-pressure measurement, compaction, context cache, selective fetch, checkpoints, and recovery surfaces
Living State	Experience packets, capability confidence, belief candidates, promoted knowledge, and preview/debug tools
Governance	Recall-quality scoring, provenance checks, duplicate detection, safe merge, archive candidates, and continuity reports
Work continuity	Goals, checkpoints, decision/error retrieval, work-ledger survival, causal stitching, and session handoff
Auto-documentation	Project-scoped architecture, decisions, changelog, runbook, system-map, debug, and memory artifacts
Storage layer	PostgreSQL for the complete feature set; SQLite for a zero-service local core

The complete subsystem and tool inventory is in docs/FEATURES.md.

How continuity flows

flowchart LR
    A[OpenCode agent] --> H[Hooks and tool surface]

    H --> AB[AgentBook]
    H --> ME[Memory engine]
    H --> LS[Living State]
    H --> CC[Context control]
    H --> WC[Work continuity]

    AB --> DB[(PostgreSQL or SQLite)]
    ME --> DB
    LS --> DB
    CC --> DB
    WC --> DB

    DB --> RE[Re-entry compiler]
    DB --> RC[Recall and context cache]
    RE --> A
    RC --> A

    AB --> FP[AGENTBOOK_STATE.md]
    FP --> A

Loading

The architecture is intentionally layered:

• AgentBook answers: “What is happening in this project right now?”
• Memory answers: “What has been learned across sessions?”
• Re-entry answers: “What does this agent need before it acts?”
• Governance answers: “Why should this information be trusted?”
• Context control answers: “What should remain active, cached, compacted, or fetched later?”

See docs/PRODUCT_ARCHITECTURE.md for the runtime boundaries and data paths.

Major systems

AgentBook: operational continuity

AgentBook records meaningful tool and session events in an append-only journal, summarizes them in bounded ranges, projects an authoritative current state, and writes a markdown front page for cold-start recovery.

• Tool events are classified by their actual operation.
• Failures retain error and exit-code evidence.
• File operations retain path evidence.
• Rules support project, session, and global scopes with explicit override behavior.
• AGENTBOOK_STATE.md is read at startup through opencode.json, before plugin hooks need to run.

Durable memory and recall

CSM stores conversations, project facts, preferences, lessons, episodic evidence, procedures, and continuity records.

Recall combines:

• vector similarity
• full-text search
• entity boosting
• memory type, tag, and importance filters
• relationship traversal
• text-only and vector-only fallback paths

Maintenance tools support embedding backfill, exact duplicate detection, safe merge/supersede, archive candidates, and governance reporting.

Re-entry and onboarding

A fresh agent can receive a structured continuity block containing:

• identity and self-continuity
• active project and phase
• current goal and checkpoint
• constraints and operating rules
• relevant memories and decisions
• promoted beliefs and advisories
• handoff state and readiness summary
• source attribution and provenance

The compiler applies priority-aware trimming rather than blindly injecting every available record.

Context control

CSM treats the context window as a managed resource.

• compaction with audit telemetry
• token-bucket and pressure analysis
• persistent context cache and manifest
• selective file-region, decision, and error retrieval
• checkpoints and checkpoint references
• source-only re-entry guards
• goal-aware system transformation
• causal stitching across sessions

Living State

The Living State layer records structured experience and derives revisable internal state.

• experience packets for successes, failures, milestones, decisions, and observations
• per-capability confidence with success/failure reconciliation
• belief candidates and evidence-backed knowledge
• controlled promotion into durable memory
• advisory preview and debug surfaces
• explicit preview and enablement gates for higher-risk behavior

Governance and trust

Memory is useful only when its limits are visible.

CSM includes:

• append-only evidence where history matters
• provenance and source attribution
• direct, inferred, and gap evidence distinctions
• recall-quality scoring
• duplicate and archive-candidate reports
• non-destructive merge/supersede behavior
• continuity resilience reporting
• database migration ledgers
• PostgreSQL matrix verification and backup/restore drills

Quick start

Runtime requirement: Node.js ^22.22.2, ^24.15.0, or >=26.0.0.

1. Configure the project

Create a .env in the project where the agent host will run. SQLite is the smallest local setup:

CSM_DATABASE_PROVIDER=sqlite
CSM_SQLITE_PATH=.data/csm-memory.db
CSM_EMBEDDING_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434

For the complete feature path, use PostgreSQL instead:

CSM_DATABASE_PROVIDER=postgres
CSM_DATABASE_URL=postgresql://csm_user:replace-me@localhost:5432/csm
CSM_REQUIRE_EXPLICIT_DATABASE_URL=true
CSM_EMBEDDING_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434

Use CSM_EMBEDDING_PROVIDER=openai with OPENAI_API_KEY if OpenAI embeddings are preferred. Never commit .env.

2. Initialize storage

npx --yes --package=opencode-cross-session-memory@1.0.0 csm-init

This applies the versioned schema safely and can be rerun during an upgrade. Back up production storage before upgrading.

3. Verify before first use

npx --yes --package=opencode-cross-session-memory@1.0.0 csm-doctor --online

Doctor checks the package, Node runtime, strict configuration, security baseline, database, complete migration history, and configured embedding model. It never includes credentials or memory content in its report. See CSM Doctor and Troubleshooting for JSON output and common fixes.

4. Connect an agent host

For OpenCode, add the pinned package and turn-1 continuity file to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["AGENTS.md", "AGENTBOOK_STATE.md"],
  "plugin": [["opencode-cross-session-memory@1.0.0", {}]]
}

For Codex, add the packaged MCP command to project .codex/config.toml:

[mcp_servers.cross_session_memory]
command = "npx"
args = ["--yes", "--package=opencode-cross-session-memory@1.0.0", "csm-mcp"]
cwd = "."
startup_timeout_sec = 30
tool_timeout_sec = 120
required = true
default_tools_approval_mode = "writes"

The Codex MCP bridge exposes explicit memory, context, lesson, checkpoint, and handoff tools; it does not receive OpenCode's automatic lifecycle hooks. See Codex Installation for live verification and the PostgreSQL-only marketplace-plugin option.

Pin the package version so an upgrade is an intentional, testable change.

5. Start a fresh task

Start the configured host in the project. OpenCode creates and updates AGENTBOOK_STATE.md as activity is captured. In Codex, verify csm_runtime_status, then explicitly request a context brief or memory operation for the current project before normal work begins.

Source checkout for contributors

The package entrypoint is dist/index.js. For local development rather than a packaged install:

git clone https://github.com/NovasPlace/CSM.git
cd CSM
npm ci
npm run build
npm run db:setup
npm run doctor -- --online

Maintainers can run the complete release gate with:

npm run verify:release

Database modes

Capability	PostgreSQL	SQLite
Core save, search, list, delete, lessons, and transcripts	Yes	Yes
AgentBook events, state, summaries, and rules	Yes	Yes
Runtime status and local continuity basics	Yes	Yes
Vector backfill and advanced maintenance	Yes	No
Belief promotion and Living State analysis	Yes	No
Recall-quality and continuity resilience reports	Yes	No
Context cache, checkpoints, goals, and advanced review tools	Yes	No
Enterprise backup/restore verification	Yes	No

SQLite is deliberately a smaller local mode. PostgreSQL is the target when the entire continuity stack is required.

Tool surface

The full PostgreSQL runtime can register up to 50 tools across six groups:

Group	Count	Examples
Memory and governance	19	csm_memory_search, csm_memory_lesson, csm_memory_merge, csm_memory_governance_report
Living State	8	csm_belief_scan, csm_belief_promote, csm_self_model, csm_living_state_preview
AgentBook	3	csm_agentbook_events, csm_agentbook_state, csm_agentbook_rule
Continuity and runtime	7	csm_onboard_agent, csm_reentry_preview, csm_continuity_report, csm_runtime_status
Checkpoints and goals	6	create_checkpoint, expand_checkpoint_ref, goal_set, goal_list
Context cache and review	7	context_search, context_fetch_file_region, context_fetch_last_error, context_fault

Some tools are conditional on provider or runtime state. The exact catalog and availability rules are documented in docs/FEATURES.md.

Configuration

Core environment variables:

Variable	Default	Purpose
CSM_DATABASE_PROVIDER	postgres	Select postgres or sqlite
CSM_DATABASE_URL	postgres://localhost/csm	PostgreSQL connection string
CSM_SQLITE_PATH	—	SQLite database path
CSM_EMBEDDING_PROVIDER	ollama	Embedding provider
CSM_EMBEDDING_DIMENSIONS	768 for Ollama, 1536 for OpenAI	Expected vector dimension; changing it requires a schema migration
OLLAMA_HOST	http://localhost:11434	Ollama endpoint
OPENAI_API_KEY	—	Required when the OpenAI embedding provider is selected
CSM_REENTRY_PREVIEW_ONLY	false	Preview re-entry instead of injecting it
CSM_BELIEF_PROMOTION_ENABLED	false	Enable controlled belief promotion

Configuration is loaded from the environment and validated before the runtime starts.

Repository map

src/                 Runtime, storage, recall, governance, hooks, and tools
src/hooks/           OpenCode lifecycle integration and system transforms
src/schema/          PostgreSQL and SQLite schema ownership
test/                Main automated regression suite
scripts/             Database, audit, benchmark, and operational commands
migrations/          Migration artifacts and historical schema changes
docs/                Product docs, contracts, evidence, and phase history
AGENTBOOK_STATE.md   Generated turn-1 project state
AGENTS.md            Repository operating guidance

Development gates

npm run typecheck
npm run build
npm run lint:src
npm test
npm run drill:backup-restore

The source lint gate is locked at zero errors and a bounded warning baseline. Database-sensitive changes should also exercise schema initialization, migration compatibility, and the backup/restore drill.

Contribution expectations are defined in the repository contribution guide.

Documentation

• Documentation index
• Feature and tool map
• Product architecture
• Codex installation
• Configuration reliability
• Data privacy and lifecycle
• Schema support matrix
• Startup and rollback
• Release process

Project status

CSM is actively developed and currently optimized for local and self-hosted agent workflows. The repository is source-first, PostgreSQL is the complete feature path, and SQLite provides a deliberately narrower local core.

Security

Memory systems can retain sensitive project context. Review SECURITY.md before using CSM with private source code, credentials, customer data, or regulated information.

License

MIT. See LICENSE.