Skip to main content
Glama

trace-mcp

I built this because I got tired of being a stranger to my own AI. Every time I open Cursor to write code, or Claude to plan something, I have to re-explain who I am, what I'm working on, and what I decided yesterday.

trace-mcp fixes that. It's a local-first memory layer that runs as an MCP server. It holds your context in one SQLite file you actually own, so it follows you across whatever AI tools you use, instead of being trapped inside someone else's cloud.

Three ideas

  1. One file. Everything lives in ~/.trace/trace.db. Copy it, back it up, delete it.

  2. Receipts. A memory without a source quote and a date is a rumor. trace stores both.

  3. Review. The model proposes. You approve. Nothing becomes active on its own.

Related MCP server: jevmem-mcp

How it works

An MCP client (like Cursor or Claude Desktop) calls remember with a sentence and a supporting quote. The memory lands in a pending queue. You approve it in the CLI or in the local inspector. The model can't approve its own memories (see Review stays with you).

Recall searches active memories using SQLite FTS5, includes your pinned memories, and fills any empty slots with the most recent ones.

When something changes, you call replace. The new memory is queued as pending. On approval, the old row is marked superseded, gets an end date, and links to its replacement. Nothing is deleted, so you can see what used to be true and when it stopped being true.

Install

Requires Node 20 or newer.

npm install -g trace-memory-mcp
trace init

If npm warns that better-sqlite3 has install scripts that weren't run (npm 11 and newer), install with:

npm install -g --allow-scripts=better-sqlite3 trace-memory-mcp

Getting EACCES: permission denied? Don't use sudo. Point npm at a folder you own instead:

npm config set prefix ~/.npm-global --location=user
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc && exec bash

trace init creates ~/.trace/trace.db. Use --db <path> or TRACE_DB to put it somewhere else.

Connect a client

trace runs as an MCP server over stdio with trace serve.

Claude Code: available in every folder:

claude mcp add --scope user trace -- trace serve

Claude Desktop: add this to claude_desktop_config.json:

{
  "mcpServers": {
    "trace": {
      "command": "trace",
      "args": ["serve"]
    }
  }
}

Cursor: add the same block to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project.

If the client can't find trace on its PATH, use "command": "npx", "args": ["-y", "trace-memory-mcp", "serve"].

Review stays with you

By default the MCP server only exposes tools that propose or read: remember, replace, recall, pending and stats.

Approving, rejecting, forgetting, pinning and exporting happen in the CLI or the inspector, where you're the one deciding. That's the point: a model, or text it read on a web page, can't slip a memory into your active set.

If you really want clients to review too, start the server with trace serve --allow-review (or set TRACE_MCP_ALLOW_REVIEW=1).

Agents with a shell. Tools like Claude Code can also run terminal commands, so a model could call trace approve directly. Block that in the agent's own permissions. For Claude Code, in ~/.claude/settings.json:

{
  "permissions": {
    "deny": ["Bash(trace approve:*)", "Bash(trace pin:*)", "Bash(trace forget:*)", "Bash(trace export:*)"]
  }
}

Commands you type yourself (! trace approve <id> in Claude Code) still work.

Receipts

Over MCP, remember and replace require evidence: the person's own words, quoted. A model can't store a memory it can't back up.

From the CLI, --evidence is optional, but a memory without one is marked no receipt in recall, the inspector and exports, so you can tell facts from rumors.

Review queue

trace pending                 # what's waiting
trace approve m_abc123        # make it active
trace reject m_abc123         # drop it
trace inspect                 # local web UI at http://127.0.0.1:4747

The inspector only listens on 127.0.0.1 and only accepts requests addressed to 127.0.0.1 or localhost from its own pages, so other websites open in your browser can't read or change your memories.

CLI

trace remember "I prefer tabs over spaces" --kind preference --evidence "tabs, always" --source chat
trace recall "editor setup"
trace replace m_abc123 "I moved to Amsterdam" --evidence "we moved last week"
trace pin m_abc123
trace forget m_abc123
trace list --status superseded
trace export --format md > memories.md
trace doctor

Kinds: identity, fact, preference, event. Run trace help for every option.

Recall

recall returns up to --limit memories (default 8):

  1. pinned memories, capped at half the slots when there are search matches

  2. full-text matches (SQLite FTS5, porter stemming, Unicode-aware)

  3. the rest of the pinned memories

  4. the most recent memories, only to fill empty slots

Development

npm install
npm test
npm run build

License

MIT

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

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides persistent local memory functionality for AI assistants, enabling them to store, retrieve, and search contextual information across conversations with SQLite-based full-text search. All data stays private on your machine while dramatically improving context retention and personalized assistance.
      3
      -
    • A
      license
      A
      quality
      B
      maintenance
      Provides AI agents with a persistent long-term memory over a single SQLite file, letting them write, screen, consolidate, and recall notes across sessions without any generative LLM in the loop. Recall judges relevance, follows links between notes, and signals when memory is insufficient, so agents get one to three useful facts per question instead of a generic top-k list.
      11
      65 PyPI
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives AI agents a local-first, persistent memory backed by a single SQLite file, letting them save decisions, preferences, and facts, then recall them by meaning or keyword across sessions and projects. Exposes tools for loading pinned context, searching, adding, updating, listing, and deleting memories, so agents stop forgetting between sessions.
      10 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to keep durable long-term memory on the user's own machine, writing sessions and messages into a local SQLite database and retrieving them via keyword, exact, or optional semantic search with surrounding context. Runs entirely offline over stdio, so no cloud service or API key is required to give an agent recall across sessions.
      1
      MIT