---
## What is open-mem?
open-mem is a plugin for [OpenCode](https://opencode.ai) that gives your AI assistant memory across sessions. It runs in the background — when you read files, run commands, or edit code, it captures what happened. During idle time, it compresses those captures into structured observations using AI. Next session, it injects a compact summary into the system prompt so the agent picks up where you left off.
It also works with **Claude Code**, **Cursor**, and any **MCP-compatible client**.
### How it works
You use tools, open-mem captures the outputs, AI compresses them into structured observations, and SQLite stores everything locally. Next session, a compact index gets injected into the system prompt so the agent picks up where you left off.
## Quick start
```bash
npx open-mem
```
That's it. This adds `open-mem` to your OpenCode plugin config automatically. It starts capturing from your next session.
Or install manually:
```bash
bun add open-mem
```
Then add to your OpenCode config (`~/.config/opencode/opencode.json` or `.opencode/opencode.json`):
```json
{
"plugin": ["open-mem"]
}
```
### AI compression (optional)
By default, open-mem uses a basic metadata extractor. For semantic compression, add an AI provider:
```bash
# Google Gemini — free tier available
export GOOGLE_GENERATIVE_AI_API_KEY=...
```
Also supports Anthropic, AWS Bedrock, OpenAI, and OpenRouter. Auto-detects from environment variables. See [Configuration](docs/configuration.md) for all providers.
## Features
**Search & retrieval** — hybrid search combining FTS5 full-text, vector embeddings (via sqlite-vec), knowledge graph traversal, and Reciprocal Rank Fusion. No external vector database needed.
**AI compression** — raw tool outputs distilled into typed observations (decision, bugfix, feature, refactor, discovery, change) with titles, narratives, concepts, and importance scores. 5 providers with automatic fallback chain.
**Progressive disclosure** — a token-budgeted index is injected into the system prompt. The agent sees *what* exists and decides *what to fetch*. Typical compression ratio: ~96%.
**Knowledge graph** — automatic entity extraction with relationships. Graph-augmented search finds connections across sessions that keyword search would miss.
**Revision lineage** — observations are immutable. Updates create new revisions that supersede the previous one. Deletes are tombstones. Full audit trail.
**9 memory tools** — `memory.find`, `memory.create`, `memory.history`, `memory.get`, `memory.revise`, `memory.remove`, `memory.transfer.export`, `memory.transfer.import`, `memory.help`. See [Tools reference](docs/tools.md).
**AGENTS.md generation** — auto-generates a root `AGENTS.md` context file by default on session end (or per-folder files in `dispersed` mode) so the agent has project awareness even without the plugin loaded.
**Web dashboard** — timeline, sessions, search, stats, operations, and settings. Real-time updates via SSE. Config control plane with live preview and rollback.
**Privacy-first** — all data stored locally in `.open-mem/`. Automatic redaction of API keys, tokens, passwords. `` tags to exclude content entirely. See [Privacy & Security](docs/privacy.md).
## Multi-platform
open-mem isn't limited to OpenCode. Dedicated adapters bring the same capabilities to other tools:
| Platform | Integration |
|----------|------------|
| **OpenCode** | Native plugin (hooks + tools) |
| **Claude Code** | `bunx open-mem-claude-code --project /path/to/project` |
| **Cursor** | `bunx open-mem-cursor --project /path/to/project` |
| **Any MCP client** | `bunx open-mem-mcp --project /path/to/project` |
See [Platform Adapters](docs/platforms.md) for setup details.
## Dashboard
```bash
export OPEN_MEM_DASHBOARD=true
# Access at http://localhost:3737
```
Six pages: Timeline, Sessions, Search, Stats, Operations, Settings. The Settings page doubles as a config control plane — preview changes, apply them, roll back if needed.
## SQLite resiliency contracts
open-mem now uses a fail-safe multi-process model for SQLite. Startup and routine operations are non-destructive by default.
- **No destructive startup recovery**: if DB setup or pragma initialization fails, open-mem returns an error and does not delete `.db`, `-wal`, or `-shm` files.
- **Coordinated writes**: mutating operations use advisory lock coordination plus SQLite write-lock semantics to reduce cross-process contention.
- **Daemon-aware workers**: platform workers check daemon liveness on startup. With a healthy daemon they run in `enqueue-only` mode and signal `PROCESS_NOW`; if daemon is unavailable they automatically fall back to `in-process` mode.
- **Safe maintenance defaults**: `reset-db` runs a preflight process check and is blocked when daemon/workers are active unless explicit `--force` is provided.
### Maintenance safety workflow
Use SQLite-native maintenance first:
```bash
# Non-destructive WAL checkpoint
bunx open-mem-maintenance sqlite checkpoint --project /path/to/project --mode PASSIVE
# Non-destructive integrity check
bunx open-mem-maintenance sqlite integrity --project /path/to/project --max-errors 10
```
If a full reset is required:
```bash
# Safe-by-default reset (blocked when active processes are detected)
bunx open-mem-maintenance reset-db --project /path/to/project
# If blocked, follow CLI remediation exactly:
# 1) Stop daemon and platform workers for this project.
# 2) Retry reset-db after processes exit.
# 3) To override (destructive), rerun with --force.
# Project-scoped stop sequence (PID file based)
PROJECT=/path/to/project
for pid_file in \
"$PROJECT/.open-mem/worker.pid" \
"$PROJECT/.open-mem/platform-worker-claude.pid" \
"$PROJECT/.open-mem/platform-worker-cursor.pid"; do
if [ -f "$pid_file" ]; then
kill "$(cat "$pid_file")" 2>/dev/null || true
fi
done
# Retry safe reset after processes exit
bunx open-mem-maintenance reset-db --project "$PROJECT"
# Explicit destructive override (only after stopping daemon/workers)
bunx open-mem-maintenance reset-db --project /path/to/project --force
```
For platform workers, `{"command":"health"}` (or HTTP `GET /v1/health`) reports `status.queue.mode`:
- `enqueue-only`: daemon is healthy; worker enqueues and signals `PROCESS_NOW`.
- `in-process`: local fallback mode when daemon is unavailable, dies, or signaling fails.
Migration note: previous workflows that relied on destructive reset during startup or ad-hoc `rm -rf .open-mem/` should move to the maintenance CLI flow above so active process checks and force intent are explicit.
## Documentation
- [Getting Started](docs/getting-started.md) — installation and first steps
- [Architecture](docs/architecture.md) — internal design and data flow
- [Memory Tools](docs/tools.md) — all 9 tools with arguments and examples
- [Search](docs/search.md) — how hybrid search works
- [Configuration](docs/configuration.md) — environment variables and config file
- [Privacy & Security](docs/privacy.md) — data handling and redaction
- [Platform Adapters](docs/platforms.md) — Claude Code, Cursor, MCP server
- [Troubleshooting](docs/troubleshooting.md) — common issues and fixes
## Comparison
| | open-mem | Typical alternatives |
|---|---|---|
| Vector search | Embedded (sqlite-vec) | External service |
| AI providers | 5 + fallback chain | 1–3 |
| Search | FTS5 + Vector + RRF + Graph | FTS5 only |
| Knowledge graph | Yes | No |
| Revision history | Immutable lineage | No |
| Dashboard | Web UI with SSE | No |
| Data storage | Project-local | Global |
| License | MIT | AGPL / proprietary |
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
## License
[MIT](LICENSE)
