Documentation   •   Issues   •   Changelog

What is open-mem?

open-mem is a plugin for OpenCode 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

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:

bun add open-mem

Then add to your OpenCode config (~/.config/opencode/opencode.json or .opencode/opencode.json):

{
  "plugin": ["open-mem"]
}

AI compression (optional)

By default, open-mem uses a basic metadata extractor. For semantic compression, add an AI provider:

# 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 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.

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. <private> tags to exclude content entirely. See Privacy & Security.

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 for setup details.

Dashboard

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:

# 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:

# 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 — installation and first steps
• Architecture — internal design and data flow
• Memory Tools — all 9 tools with arguments and examples
• Search — how hybrid search works
• Configuration — environment variables and config file
• Privacy & Security — data handling and redaction
• Platform Adapters — Claude Code, Cursor, MCP server
• Troubleshooting — 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 for development setup and guidelines.

License

MIT