Skip to main content
Glama

MemoSaver

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

Node License MCP

Never start your AI session from zero.

v0.4 — the memosaver dashboard: every project as a node in one 3D memory graph, rendered from your local SQLite memory.

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.

Related MCP server: knitbrain

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

🪪 Project isolation

every read and write resolves to one project by sha256(path); the 12-char hash key (c2a7f336a470) is the handle used in URLs, CLI and MCP

🖥 Dashboard

memosaver → Dashboard serves the workspace overview, per-project pages (memories, types, sessions, FTS search) and the memory graph

🦀 Background writer

optional Rust daemon (memosaverd): one parked process, ~2 MB RSS and ~2 ms per turn instead of booting Node per activity event

🧭 Memory graph

/graph — a 3d-force-graph dashboard with every project as a node, sessions and memories one click down

⌨️ Zero-arg menu

plain memosaver opens an interactive menu: dashboard, status, projects, sessions, memories, search, doctor, install

📄 TSON context

the resume context is written as TSON (spec v1.0): keys once, -> rows per memory, ~30-60% fewer tokens than JSON

🛡 Graceful failure

MemoSaver enhances; it never blocks or crashes the agent

What's new in 0.4

  • memosaver with no arguments opens a menu — dashboard, status, projects, sessions, memories, search, doctor and install, one keystroke each. Piped or non-TTY runs keep the plain help, so scripts are unaffected.

  • The memory graph lives at /graph and draws every stored project around the workspace hub (3d-force-graph, vendored, works offline). /visual redirects there.

  • Memory records render as TSON blocks — type, importance, age and one labelled row per clause, collapsed when long, in the project page and the graph's memory tables.

  • The resume context is TSON (spec v1.0) end to end.

  • The isometric orrery is gone, replaced by the graph dashboard.

Requirements

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

  • Rust toolchain (optional): only to build the background writer with pnpm build:daemon

Quick start

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

Wire every agent at once (Claude Code, OpenCode, omp):

memosaver install

It registers the MCP server in each agent's config and injects the usage rules into ~/.claude/CLAUDE.md and ~/.config/opencode/AGENTS.md. The server entry always uses the absolute path of the Node running the installer, because agents spawn MCP servers with their own PATH — a bare node can resolve to a version without node:sqlite and the server then dies at startup. Re-running memosaver install repairs a stale entry.

Agents that support the MCP instructions field (omp) get the same rules straight from the server, with no instruction file involved.

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 -p 'process.execPath')" /path/to/memosaver/dist/mcp/entry.js

omp

memosaver install writes ~/.omp/agent/mcp.json (or ~/.omp/profiles/<name>/agent/mcp.json under a profile), which omp reads before any imported Claude Code or OpenCode config:

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

memosaver install also drops ~/.omp/agent/extensions/memosaver-auto.ts, an omp extension that runs MemoSaver automatically — see Automatic mode.

Then /mcp reload (or restart omp) and /mcp list to confirm memosaver connected.

OpenCode

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

{
  "mcp": {
    "memosaver": {
      "type": "local",
      "enabled": true,
      "command": ["/absolute/path/to/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.

Automatic mode (omp)

With the bundled omp extension installed, none of the steps above are needed on each session — the extension drives MemoSaver from omp's own event bus:

omp event

MemoSaver action

session_start

auto start — opens a session, builds the resume context

first prompt (before_agent_start)

injects the resume context once, so the agent starts with project memory

turn_end

auto log — sends the user request, assistant outcome and failed tool calls through the extraction pipeline

session.compacting

auto recall — re-injects memory into the compaction summary, so a compacted session keeps its context

session_shutdown

auto checkpoint then auto end --status completed

Subagent sessions are skipped, every call is best-effort (a missing build or an old Node disables the bridge silently), and the injected resume block tells the agent not to call session_start again — a second session_start would close the running session as interrupted.

Turn it off per run with MEMOSAVER_AUTO_DISABLE=1, or point it elsewhere with MEMOSAVER_CLI / MEMOSAVER_NODE / MEMOSAVER_DAEMON. Skip installing it with memosaver install --no-omp-extension.

Background writer (Rust)

Every agent turn writes one activity event. Booting Node for that costs ~60 MB RSS and hundreds of milliseconds of CPU per turn. Build the daemon once:

pnpm build:daemon      # cargo build --release --manifest-path rust/Cargo.toml
memosaver install      # copies it to ~/.memosaver/bin/memosaverd

The extension then calls memosaverd log for each turn:

$ memosaverd status
{"ok":true,"projects":2,"memories":5,"sessions":2}
$ /usr/bin/time -l memosaverd log -p . -s session_… "We decided to use SQLite FTS5."
{"ok":true,"captured":1,"ignored":0}
        0.00 real         0.00 user         0.00 sys
             1884160  maximum resident set size
  • One parked process — the daemon blocks in accept(); idle CPU is zero and it holds no timer.

  • Never blocks a turn — when the daemon is not running yet, log spools the event, starts it detached and exits.

  • Same rules — classification, scoring, dedupe and project/session scoping mirror src/memory/*, and the FTS triggers are the same schema, so Node and Rust write interchangeable rows. MEMOSAVER_AUTO_DISABLE=1 still turns the bridge off, and the Node CLI remains the fallback when the binary is missing.

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

# interactive menu (dashboard + the read-only commands above)
memosaver

# automation bridge (used by the omp extension)
memosaver auto start --project <path> --agent omp
memosaver auto log --project <path> --session <id> --file -
memosaver auto recall --project <path>
memosaver auto checkpoint --session <id> --goal "..." --next "..."
memosaver auto end --session <id> --summary "..."
memosaver auto status --project <path>

# diagnostics
memosaver doctor

Dashboard and memory graph

memosaver                     # interactive menu; item 1 starts the dashboard
memosaver status              # the menu is a shortcut, every subcommand still works

The dashboard is http://127.0.0.1:8888/ and starts from the menu (port 8888, browser opens automatically; Ctrl+C in the menu stops it and returns to the list). When stdin is not a TTY — a pipe, a script, CI — memosaver prints the normal help instead of the menu.

  • / — workspace overview: totals, one card per project with its hash key, memory and session counts, last activity and a live dot for active sessions.

  • /project/<id|hash|path> — one project: memory-type breakdown, FTS search box, type filter, importance bars, sessions and their status. A selector that matches nothing returns 404; a view never falls back to another project.

  • /graph — the memory graph of the whole workspace: a hub node for the workspace and one node for every stored project, sized by memory count and green while a session is active. Clicking a project opens that project's own graph — the project, its sessions, and each session's memories — with a type filter, node detail panel, KPI strip, type breakdown, session rail and the highest-importance memories underneath. /visual redirects here.

  • /api/spec — the Archify specification as JSON (kept for tooling).

The dashboard is server-rendered HTML with no client-side framework and no CDN, so it opens instantly and shows exactly what the database holds. The only client script is the graph: 3d-force-graph is vendored under vendor/3d-force-graph/ (One self-contained UMD bundle, served from /vendor/3d-force-graph.min.js), so the page works offline. Without WebGL the lists on the page still carry every fact the graph shows.

The memory graph

  • Workspace scope — one hub, every stored project around it (235 on this machine), node size from the project's memory count, green when a session is active.

  • Project scope — the project as the centre node, its latest sessions beside it, and the 240 most recent memories attached to the session that wrote them.

  • Reading it — hover for a tooltip, click a node for its detail, click a project to drill in, use the type filter to isolate one memory type, and Reset view to re-fit the camera.

  • Memory text — every memory is printed as a TSON block: type, importance, age, then one -> row per clause with its own label (brand, seo, traps) where the sentence has one. Long records collapse to a one-line summary; expanding shows the whole block. The same format is used in the project page table and in the graph's node detail panel.

  • Data honesty — the graph is only a view: the KPI strip, type breakdown, session rail and memory table beside it are rendered on the server from the same SQLite rows.

Resume context format

The resume context memosaver hands back to an agent is written as TSON v1.0 — keys once, two-space indentation, memory records as -> type: ... importance: ... content: ... rows, reserved characters quoted:

# PROJECT CONTEXT
project:
  name: memosaver
  path: /Users/me/dev/memosaver
  updated: 2026-11-14T09:12:04.531Z

# KEY CONTEXT
key_context[2]:
  -> type: DECISION importance: 0.95 content: PostgreSQL chosen for JSONB support.
  -> type: TASK importance: 0.8 content: "Migrate the web layer, then re-run the suite."

Screenshots

The workspace graph — one hub, every project, sized by memory count:

MemoSaver workspace memory graph

One project — sessions and memories around the project node, with the dashboard beside it:

MemoSaver project memory graph

Workspace overview — totals and one card per project with its hash key, counts and live dot:

MemoSaver workspace overview

Project detail — memory-type breakdown, scoped search, importance bars and the session list:

MemoSaver project detail

Static site

site/ is a standalone landing page — plain HTML, one Tailwind-built stylesheet and a small script. No framework, no runtime build:

pnpm site:build                 # tailwind -> site/build.css (committed, so Pages needs no build)
python3 -m http.server -d site  # preview at http://localhost:8000

Published to GitHub Pages on every push that touches site/: https://akufikri.github.io/memosaver/ — the workflow is .github/workflows/pages.yml. It rebuilds Tailwind in CI before publishing, so the deployed stylesheet always matches site/styles.css; if the committed site/build.css is stale it says so with a warning instead of blocking the deploy.

Everything is relative to site/, so the same directory works from the Pages root, a local server, or file://. Brand art and screenshots live in site/assets/.

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

8000

idle window that auto-flushes the buffer

memory.llm.*

off

optional LLM-backed extractor (see docs/memory.md)

search.hybrid

true

hybrid scoring for memory_search_hybrid (false = pure BM25)

search.importance_weight

0.35

importance share of the hybrid score

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, "debounce_ms": 8000 },
  "search": { "hybrid": true, "importance_weight": 0.35 },
  "resume": { "max_tokens": 4000, "max_memories": 25 }
}

Storage layout

~/.memosaver/
├── memosaver.db          # SQLite (WAL mode, FTS5) — projects, sessions, memories, checkpoints
├── config.json           # optional overrides
├── bin/memosaverd        # optional Rust background writer (memosaver install)
├── memosaverd.sock       # unix socket of the running writer (0600)
├── spool/                # events queued while the writer was down
└── logs/{memosaver,memosaverd}.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 (75 tests)
pnpm acceptance    # real stdio MCP resume check end-to-end
pnpm build         # tsc -> dist, plus the vendored Archify renderer
pnpm site:build    # Tailwind -> site/build.css (static landing page)
pnpm site:watch    # rebuild site/build.css on change

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

Documentation

License

MIT © 2026 Fikri Nurhakim. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers