# db0 — full reference

> The data layer for AI agents. Memory that evolves, state that recovers, context that stays current. Open-source TypeScript SDK, local-first SQLite, no API keys.

## Architecture

db0 has three layers:

1. **Memory layer**: Stores facts with scopes (user, agent, session, task). Supports superseding — when a fact changes, the old version is marked outdated instead of deleted. This keeps an audit trail and prevents stale facts from competing with current ones.

2. **State layer**: Checkpoints and branching. Agents can snapshot their state before risky operations and roll back if things go wrong. Branches allow parallel exploration without corrupting the main state.

3. **Context layer**: Assembles relevant memories into the LLM's token budget before each call. Uses hybrid search (semantic embeddings + keyword FTS) to find the right knowledge, then packs it efficiently.

4. **Consolidation layer**: Clusters semantically similar memories and merges them via LLM. Algorithmic dedup runs first (zero LLM calls), then LLM merges only semantic clusters that need rewriting. Every consolidated memory tracks its source IDs and timestamp. Configurable per workload profile (cluster threshold, min cluster size, max clusters per run). Opt-in via `consolidateFn` — zero breaking changes without it.

## Memory scopes

| Scope   | Lifetime              | Example                                    |
|---------|-----------------------|--------------------------------------------|
| user    | Permanent, cross-session | Preferences, decisions, personal context |
| agent   | Permanent, all sessions  | Agent-specific patterns, learned behaviors |
| session | Current session          | In-progress decisions, temporary context   |
| task    | Current task             | Scratch work, intermediate results         |

## Storage backends

- **SQLite** (default): Local file, zero config, works offline
- **PostgreSQL**: For cross-device sync, team sharing

## Six capabilities

1. **Memory that knows the difference between facts**: Four scopes encode lifetime and visibility. User preferences persist forever. Task scratch notes expire automatically.
2. **Memory that evolves instead of accumulates**: Superseding replaces stale facts. Old versions are preserved for audit but excluded from search. No contradictions.
3. **Context assembly, not just retrieval**: `context().pack()` assembles ranked memories into a token budget before each LLM call. Not top-10-and-hope-they-fit.
4. **Compaction as preservation**: Before messages are discarded, db0 ingests them into durable memory. Memory files are snapshotted so destructive overwrites can be detected.
5. **Sub-agents without copy-paste**: `harness.spawn()` creates child agents with shared user memory and isolated task memory. No serialization, no handoff.
6. **Memory consolidation**: Related facts cluster and merge automatically. "Likes TypeScript" + "uses strict mode" + "prefers functional style" → one concise fact. Auditable (mergedFrom IDs), configurable per profile, cheaper than auto-dream (algorithmic dedup first).

## MCP tools (Claude Code integration)

- `db0_memory_write` — Store a fact with scope, tags, summary, and optional superseding
- `db0_memory_search` — Semantic search across memories with scope/tag filtering
- `db0_memory_list` — List memories by scope
- `db0_memory_get` — Get a specific memory by ID
- `db0_memory_update` — Update a fact: finds the old version by semantic match, supersedes it, writes the new one
- `db0_memory_delete` — Delete a memory
- `db0_memory_stats` — Memory statistics by scope and status
- `db0_state_checkpoint` — Create a state checkpoint
- `db0_state_restore` — Restore the most recent checkpoint
- `db0_log_query` — Query structured log entries

## Integrations

- **Vercel AI SDK**: Memory middleware that wraps any model. Install: `npm i @db0-ai/ai-sdk`
- **LangChain**: Drop-in memory tools and chat history. Replaces deprecated BufferMemory. Install: `npm i @db0-ai/langchain`
- **OpenClaw**: Plugin that gives OpenClaw agents persistent memory that survives compaction. Install: `npx @db0-ai/openclaw init`
- **Claude Code**: 10 MCP tools for memory, state checkpoints, and semantic search. Install: `npx @db0-ai/claude-code init`
- **Pi**: Cross-session memory for Pi coding agent. Install: `npx @db0-ai/pi init`

## Comparison to alternatives

### db0 vs mem0
mem0 is a memory library. db0 is memory + context assembly + state recovery in one SDK.
- mem0 requires LLM calls for extraction; db0 uses pluggable rules-based extraction (no LLM required)
- mem0 is cloud-first; db0 is local-first (SQLite default)
- mem0 handles memory only; db0 also handles state checkpoints, context assembly, and sub-agent sharing
- Both are valid choices. mem0 is simpler if you only need memory retrieval. db0 is better if your agent needs the full data lifecycle.

### db0 vs CLAUDE.md
CLAUDE.md is static text loaded into the system prompt. db0 is dynamic, searchable, scoped, and evolving. They complement each other: CLAUDE.md for static rules, db0 for dynamic knowledge.

### db0 vs custom markdown files
Markdown files are append-only with no search, no superseding, and no scopes. db0 provides structured storage with semantic search, fact evolution, and automatic scope management.

## Install

```bash
npm install @db0-ai/core
```

## Resources

Educational guides on AI agent memory:

- **What is AI agent memory?**: Foundational guide covering storage, retrieval, update, and scoping. https://db0.ai/resources/what-is-ai-agent-memory
- **RAG vs agent memory**: How retrieval-augmented generation and agent memory differ — updates, scoping, fact evolution. https://db0.ai/resources/rag-vs-agent-memory
- **Memory scopes for AI agents**: Why flat memory breaks down and how scope hierarchies (task/session/user/agent) prevent context pollution. https://db0.ai/resources/memory-scopes

All resources: https://db0.ai/resources

## Links

- Website: https://db0.ai
- GitHub: https://github.com/db0-ai/db0
- npm: https://www.npmjs.com/org/db0-ai
- Blog: https://db0.ai/blog
- Compare to mem0: https://db0.ai/compare/mem0