<div align="center"> <img width="1942" height="809" alt="ChatGPT Image Aug 9, 2026, 12_03_41 AM" src="https://github.com/user-attachments/assets/e9349954-feea-4283-9567-5b7ebfad35b7" />

MemoSaver

Local-first, persistent memory & session continuity for AI coding agents.

Never start your AI session from zero.

</div>

MemoSaver is an MCP server that lives outside Claude Code / OpenCode session lifecycles. It detects the project you open, captures the decisions, errors, solutions and progress that matter, stores them in a local SQLite database — and days later hands your agent a resume context so you can say "continue where we left off" without re-explaining anything.

Monday   cd project-a && claude   → session_start → work → memories + checkpoint → session_end
Friday   cd project-a && claude   → session_start → resume context → straight back to work

Why MemoSaver?

AI agents forget everything the moment a session ends. You end up re-explaining your architecture, your decisions, and what's still pending — every single time. MemoSaver keeps the knowledge that matters (not the transcript), bind to your project, on your own machine, independent of which agent you use.

Features

📁 Project detection	deterministic sha256(path) ids; same folder = same project
🧠 Sessions	active / completed / interrupted, auto-close on re-open
⚡ Auto memory	10-type classifier, importance scoring, dedupe, buffered extraction
🔎 Search	FTS5 (BM25) keyword search + optional hybrid token-overlap ranking
🧰 Checkpoints	manual + automatic; token-budgeted resume context (~2–5k tokens)
🤖 Agent-agnostic	Claude Code, OpenCode, cursor, and any MCP-capable agent
🔒 Local-first	zero cloud, zero network, zero native deps — your data is yours
🖼 3D visualization	interactive WebGL memory network (memosaver visual)
🛡 Graceful failure	MemoSaver enhances; it never blocks or crashes the agent

Requirements

• Node.js >= 22.5 (uses the built-in node:sqlite — no native compilation, no install step)

Quick start

git clone <your-repo-url>/memosaver
cd memosaver
pnpm install && pnpm build
npm link            # registers `memosaver` and `memosaver-mcp`

Verify:

memosaver doctor

Connect as MCP

Claude Code

The CLI command adds it to ~/.claude.json. Scope user to make it available in every project:

claude mcp add memosaver --scope user -- node /path/to/memosaver/dist/mcp/entry.js

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "memosaver": {
      "type": "local",
      "enabled": true,
      "command": ["node", "/path/to/memosaver/dist/mcp/entry.js"]
    }
  }
}

There used to be a "type": "stdio" variant in older docs — OpenCode now expects the local shape above.

Any MCP client

Run the server binary directly over stdio:

node /path/to/memosaver/dist/mcp/entry.js

and point your client at it as a stdio/local server (most clients mirror either the Claude Code or OpenCode shape above).

Usage in chat

Start a session, work, checkpoint, close — then resume later:

● Start:      "Start a MemoSaver session for this project."
● Capture:    "Save this to MemoSaver: <decision/error/solution>"
● Checkpoint: "Checkpoint: completed=..., pending=..., next_action=..."
● Close:      "Finish the MemoSaver session."
● Resume:     "Continue from where we left off (use MemoSaver memory)."

session_start automatically returns a resume context whenever the project has prior memory.

MCP tools

Tool	Purpose
session_start	open a project; returns resume context if a previous session exists
session_checkpoint	record goal, current state, completed, pending, blockers, next
session_end	close a session (completed/interrupted); auto final checkpoint
session_status	inspect sessions
session_timeline	chronological checkpoints + memories of a session
memory_insert	explicitly persist a memory
memory_update	edit content / type / importance of a memory
memory_recall	top memories by importance
memory_search	FTS5 BM25 keyword search
memory_search_hybrid	BM25 + lexical token-overlap ranking
memory_delete	remove a memory
memory_capture	run extraction immediately on raw text
memory_export / memory_import	portable JSON backup / restore
activity_log	buffer one raw event for automatic extraction

CLI reference

memosaver status                          # storage + counts
memosaver projects                        # all known projects
memosaver sessions [project_path]         # sessions
memosaver session <id> [--end|--interrupt|--timeline]

# memories
memosaver memory list --project <path>
memosaver memory search "jwt auth" --project <path>
memosaver memory search "jwt" --project <path> --hybrid
memosaver memory save "postgres chosen for JSONB" --project <path>
memosaver memory update <id> --type DECISION
memosaver memory recall --project <path>
memosaver memory delete <id>
memosaver memory export --project <path> --out memories.json
memosaver memory import memories.json

# diagnostics
memosaver doctor

Interactive visualization

<img width="1636" height="1005" alt="image" src="https://github.com/user-attachments/assets/4d132138-0ed6-4164-aea9-0015c32a4a19" />

Explore your memory graph in 3D from the browser:

memosaver visual               # serves on http://127.0.0.1:8888/visual
memosaver visual --port 9000   # custom port
memosaver visual --no-open     # don't auto-open the browser

• 3D network view — projects at the center, sessions in rings around them, memories & checkpoints orbiting their session. All rendered with WebGL (three.js), no backend chat required.
• Group by project — pick a project from the header to focus only that network.
• Interactive — drag any node, orbit / zoom / pan, hover for tooltips, auto-orbit toggle.
• Graceful fallback — if WebGL is unavailable the UI shows a clear message instead of a blank screen.

Configuration

Key	Default	Description
home / MEMOSAVER_HOME	~/.memosaver	storage root
memory.min_importance	0.3	minimum score to keep extracted memory
memory.buffer_size	20	buffered activity_log entries before flush
memory.debounce_ms	20000	time window to auto-flush the buffer
memory.llm.*	off	optional LLM-backed extractor (see docs/memory.md)
resume.max_tokens	4000	resume-context budget
resume.max_memories	25	max memories in resume context
logger.level	info	log verbosity

// ~/.memosaver/config.json
{
  "memory": { "min_importance": 0.3, "buffer_size": 20 },
  "resume": { "max_tokens": 4000, "max_memories": 25 }
}

Storage layout

~/.memosaver/
├── memosaver.db      # SQLite (WAL mode, FTS5) — projects, sessions, memories, checkpoints
├── config.json       # optional overrides
└── logs/memosaver.log

Backup is simply copying memosaver.db, or use memory export. Everything lives on your machine.

Troubleshooting

memosaver doctor     # db health, FTS5, config, storage, project detection, agent wiring
memosaver status     # quick counts

• Tools not showing in Claude Code? Restart Claude Code after claude mcp add.
• Tools not showing in OpenCode? Verify the local shape above, then restart.
• doctor fails on node:sqlite? Downgrade to Node >= 22.5 or upgrade.
• Never needed: cloud, database server, Docker, or a vector API.

Development

pnpm install
pnpm typecheck
pnpm lint
pnpm test          # unit + integration + E2E (57 tests)
pnpm acceptance    # real stdio MCP resume check end-to-end
pnpm build

Working on the code? See docs/development.md.

Documentation

• docs/architecture.md — layers, decisions, failure handling
• docs/mcp.md — full MCP interface & resume contract
• docs/memory.md — classifier, scorer, hybrid search, optional LLM extractor
• docs/sessions.md — session state machine, auto-checkpoint, resume
• docs/development.md — scripts, conventions, gotchas
• IMPLEMENTATION_PLAN.md — milestones & roadmap
• IMPLEMENTATION_STATUS.md — what's shipped vs pending

License

MIT © 2026 Fikri Nurhakim. See LICENSE.