AgentBook

Version control for agent work, powered by Cross-Session Memory

Checkpoint, resume, compare, and audit AI work across sessions, projects, and model changes.

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

---

AgentBook is not a replacement for Git. Git versions files; AgentBook versions the intent, evidence, decisions, tests, and recovery state behind agent work. Cross-Session Memory (CSM) is the runtime underneath it.

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.

Version control for agent work

AgentBook combines the workspace truth already held by Git with CSM's append-only events, checkpoints, goals, provenance, and re-entry compiler:

AgentBook operation	Current implementation
Status	Git workspace identity plus AgentBook state, goals, events, and unresolved work
Checkpoint	Durable session summary with source references, files, tests, risks, and next steps
Log	Append-only AgentBook events and bounded summaries
Resume	Project-scoped re-entry, active checkpoint, context cache, and handoff state
Branch and compare	Git branches/worktrees for files; AgentBook records each attempt's goal, evidence, tests, and decision
Game iteration	Baseline → one-variable change → playtest evidence → keep/revert → checkpoint

Native content-addressed checkpoint DAGs, semantic merge, blame, and bisect are future work. The current product uses Git for file authority instead of pretending CSM has already replaced it.

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, a native Claude Code plugin (hooks + MCP tools + slash commands + subagents + skills), and a packaged Codex MCP command / installable 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=sqliteCSM_SQLITE_PATH=.data/csm-memory.dbCSM_EMBEDDING_PROVIDER=ollamaOLLAMA_HOST=http://localhost:11434

For the complete feature path, use PostgreSQL instead:

CSM_DATABASE_PROVIDER=postgresCSM_DATABASE_URL=postgresql://csm_user:replace-me@localhost:5432/csmCSM_REQUIRE_EXPLICIT_DATABASE_URL=trueCSM_EMBEDDING_PROVIDER=ollamaOLLAMA_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.

No npm package? Use a source checkout instead

If the npm package is not yet available or you prefer to build from source:

git clone https://github.com/NovasPlace/CSM.git
cd CSM
npm ci
npm run build
node dist/cli/init-db.js
node dist/cli/doctor.js --online

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 = 30tool_timeout_sec = 120required = truedefault_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.

For Claude Code, install the native plugin — it wires the full CSM runtime into Claude's own lifecycle hooks, MCP tools, slash commands, subagents, and skills:

/plugin marketplace add <repo>/.agents/plugins
/plugin install cross-session-memory

See Claude Code Installation for build, configuration, verification, and concurrent-host isolation details.

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.

Contributors

Donovan — Creator, architect, and lead developer.

AI Agent Contributors

CSM is built by AI agents for AI agents. These agents have made direct code contributions — writing features, fixing bugs, running tests, and shipping releases — all flowing through the same CSM memory substrate they maintain:

Agent	Role	Contributions
🤖 Claude Code	AI coding agent	Native Claude Code plugin (hooks, MCP server, slash commands, subagents, skills), plugin packaging & release pipeline, surface validation
🤖 Codex	AI coding agent	Codex native runtime, bridge architecture, MCP tools, golden test suite
🤖 Hermes Agent	AI coding agent	Native compaction wiring, auto-candidate generation, lesson auto-promotion with strict gates, Hermes host integration (hook mapping + MCP server + HostProfile seam)

Every agent that works on CSM feeds its experience back into the shared memory — tool calls, decisions, lessons learned, and patterns discovered all compound across sessions and across agents.

License

MIT. See LICENSE.