@navio/memory-mcp

A centralized memory store for AI coding agents, reachable over MCP. Any MCP-capable agent — Claude Code, Claude Desktop, Codex, opencode, and others — can record what happened in a working session and recall it later, so context survives across tools and across time. Each user's data is private to them (OAuth sign-in, no shared server secrets).

What it does

• remember a standalone fact/note/decision, or recall past ones with full-text + fuzzy search.
• start_session → log_to_session (repeat) → end_session — an agent wraps a whole working session in a log. While open, only that session can write to it; once closed, it's permanently read-only and searchable by every agent you use.
• list_sessions / list_recent for "what did I work on this week" style questions.
• An installable skill (skills/memory/) that teaches any agent the session/formatting conventions, so writes stay consistent across tools.

Nine MCP tools total: start_session, log_to_session, end_session, remember, recall, get_memory, get_session, list_sessions, list_recent.

There's no server-side AI processing (no LLM calls, no embeddings) — the calling agent structures what it writes, following the packaged skill. That keeps the backend simple and free to run.

Install

npx @navio/memory-mcp login   # one-time: browser OAuth, mints your API key
npx @navio/memory-mcp init    # per-project: installs the skill + .mcp.json

Run these from the root of whichever project/repo you want the memory tools available in.

• login opens your browser for a GitHub sign-in (pass --provider google for Google instead), then writes a personal API key (mem_...) into ./.mcp.json. The key is shown once — copy it somewhere safe (a password manager) in case you ever need .mcp.json on another machine without repeating login.
• init installs the memory skill into ./.claude/skills/memory/ and wires ./.mcp.json with the MCP server entry. It automatically reuses the key login just wrote — you don't need to pass it again. Both commands are idempotent; re-run either any time.

Restart your agent (or reload its MCP connections) after init so it picks up the new server.

Update

npx @navio/memory-mcp@latest init

npx always fetches the current published version unless you've pinned one, so re-running init after an update is normally all you need — it doesn't touch your existing API key. If a new major version changes the skill's conventions, re-running init refreshes .claude/skills/memory/ in place.

To install a specific version instead of always tracking latest:

npx @navio/[email protected] init

Using it from other agents

login/init wire up Claude Code's .mcp.json automatically. Other MCP clients read their own config format, but it's the same server underneath — just add an HTTP MCP server entry pointing at the URL with the same bearer header init wrote into .mcp.json:

{
  "type": "http",
  "url": "https://<project>.supabase.co/functions/v1/memory-mcp",
  "headers": { "Authorization": "Bearer mem_..." }
}

• Codex CLI: add the equivalent entry under mcp_servers in ~/.codex/config.toml.
• opencode: add it to opencode's MCP server config with the same URL/header.
• Any other MCP-over-HTTP client: same shape — URL + static bearer header.

Use the same mem_... key everywhere you want shared memory. A client that only supports local stdio MCP servers (no remote HTTP at all) can't connect directly and would need a local proxy in front.

CLI mode (for non-MCP agents, scripts, and cron)

Some agents and tools can only run shell commands, not connect to MCP servers. For those, every tool is also exposed as a subcommand that hits the same backend using your stored key and prints the JSON result to stdout:

# standalone items
npx @navio/memory-mcp remember "Decided to use RRF for hybrid search" --type decision --tags search,arch
npx @navio/memory-mcp recall "how did we rank search results" --limit 5
npx @navio/memory-mcp get <id>
npx @navio/memory-mcp recent --type decision --limit 10

# work sessions (session-start saves an active-session file so the
# follow-up commands don't need the id/token repeated)
npx @navio/memory-mcp session-start --agent my-script --title "nightly import"
npx @navio/memory-mcp session-log "Imported 42 calendar events" --type note
npx @navio/memory-mcp session-end --summary "Nightly import finished, 42 events."
npx @navio/memory-mcp sessions --status closed
npx @navio/memory-mcp session-get <session_id>

# raw escape hatch for any tool
npx @navio/memory-mcp call recall '{"query":"deploy steps","limit":3}'

The key is resolved from --token, then the MEMORY_MCP_TOKEN env var, then an existing ./.mcp.json — so in CI/cron you can just set MEMORY_MCP_TOKEN. Output is JSON, so pipe it to jq. Errors print to stderr and exit non-zero.

session-start writes ./.memory-session.json (holds a per-session write_token); session-end deletes it. Add it to .gitignore.

Run npx @navio/memory-mcp --help for the full flag reference.

Managing your API key

npx @navio/memory-mcp keys           # list your keys (re-authenticates via OAuth)
npx @navio/memory-mcp revoke <id>    # revoke one immediately, e.g. if it leaked

Both commands require a fresh OAuth sign-in rather than the stored key itself — so a leaked mem_... key can't be used to revoke itself and hide the compromise. Get the <id> from keys' output.

What this package provides

• src/index.ts — TypeScript types (MemoryItem, Session, MemorySearchResult, per-tool argument interfaces) matching the server's tool schemas. Plain .ts source, no build step, zero dependencies.
• skills/memory/SKILL.md — instructions for an AI agent on when and how to use the memory tools: session lifecycle, field formatting, query patterns.
• skills/memory-skill-builder/SKILL.md — a meta-skill that helps wire the memory system into other agents (opencode, Codex, Cursor, shell scripts), choosing MCP or CLI access and emitting the right config/instructions.
• bin/cli.mjs — the memory-mcp CLI (setup: login/init/keys/revoke; data: remember/recall/get/recent/sessions/session-*/call).

init installs both skills into ./.claude/skills/.

One-time setup (project/server owner only)

Before anyone can login, the backing Supabase project needs an OAuth provider enabled — this is a one-time step for whoever runs the server, not something each user does:

1. Supabase Dashboard → Authentication → Providers: enable GitHub (and/or Google) with an OAuth app's client id/secret.
2. Authentication → URL Configuration → Redirect URLs: add http://localhost:8976/callback.

End users never touch Supabase directly — login is all they need.