trailmem

Persistent, local-first graph memory for AI coding agents.

Trailmem gives agents durable cross-session memory without provider lock-in: a local SQLite knowledge graph, typed relationships, explicit knowledge evolution, and token-disciplined briefings. It is designed for multiple local agents—Claude, Kiro, Codex, OpenCode, Kilo, and Gemini—to share useful project knowledge without silently creating junk memories.

Quick start

Same commands on Windows, macOS, and Linux.

Install (recommended: uv — no Python needed)

trailmem is a command-line tool, so install it as one — this puts trailmem on your PATH in every terminal. The cleanest way is uv, a standalone binary that needs no pre-installed Python (it fetches one for you):

# 1. Install uv (standalone — does NOT require Python):
curl -LsSf https://astral.sh/uv/install.sh | sh          # Linux / macOS
# Windows (PowerShell):  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. Install trailmem (uv downloads a Python for it if you don't have one):
uv tool install trailmem

Already have Python and prefer pipx? pipx install trailmem then pipx ensurepath works the same way (pipx needs an existing Python).

<details> <summary>Plain <code>pip</code> (only inside a virtualenv or CI)</summary>

pip install trailmem

pip install drops the trailmem command into the current Python's bin/Scripts folder, which is often not on your PATH — a global pip install --user or a system Python will leave you with zsh: command not found: trailmem (and on Debian/Ubuntu, a PEP 668 "externally-managed" error). Use uv/pipx above unless you're deliberately working inside an activated virtualenv. If you already ran pip install and hit command not found, either activate the venv you installed into or run it as python -m trailmem — or just switch to uv tool install trailmem.

</details>

Set up and register

trailmem setup          # creates ~/.trailmem/, inits DB, downloads the default embedding model (~130 MB, one time)
trailmem doctor         # health check

# Register the MCP server with your agent host(s):
trailmem integrate      # detects installed agent hosts, asks before writing any config

trailmem integrate auto-detects nine hosts: Claude Code, Codex, Kiro, Kilo, OpenCode, Antigravity, Zed, Cursor, Windsurf. It shows what it found, asks once (y/N), backs up every config it touches (.bak-trailmem), skips hosts that are already registered, and never rewrites a config it can't parse losslessly (JSONC with comments gets the manual entry printed instead). On Claude Code it also installs a /tm-save slash command.

Saving a session before you exit

An agent that forgets to record memory (or a hard /exit) can drop a session's context — a host end-of-session hook can't help, because it runs after the agent is gone and never sees the conversation. Only the live agent, mid-session, can capture. trailmem gives it a portable trigger plus reminders.

Trigger a save — use whichever your client supports (they all end in the same instruction: extract this session's decisions/lessons/tasks and call trailmem_store):

How	Works in	Invoke
MCP prompt save_session (zero-config, portable)	Any client that surfaces MCP prompts	Claude Code /mcp__trailmem__save_session · VS Code /mcp.trailmem.save_session · Cursor & Windsurf: slash/prompt list · Zed: text threads only
/tm-save command (installed by integrate)	Claude Code	/tm-save
Plain text (always works)	Every client — the trailmem_store tool is universal	Type "save this session to trailmem"

Clients with no prompt support (e.g. Codex, aider) use the plain-text path — nothing is lost, the tool is always available. If your agent supports custom slash commands, you can point one at the same instruction yourself; formats differ per host, so check that agent's command-file docs (and avoid the config landmines below).

Reminders so you remember to trigger it:

• Statusline — trailmem statusline prints 🧠 trailmem: N saved this session, or ⚠ 0 saved · save before exit when nothing's captured yet. Reads session_id from stdin JSON (Claude Code) or CLAUDE_CODE_SESSION_ID/KIRO_SESSION_ID env; read-only, always exits 0. Wire it into your host's statusline, or run it standalone.
• Welcome tip — the briefing ends with a save reminder (shown by hosts that surface the session-start output, e.g. Codex, Kilo).
• Next-session flag — if the previous session stored nothing, the next welcome opens with a loud reminder.

Wiring an unlisted agent yourself? MCP config formats are not uniform, and a wrong guess can break the agent's launch. Known landmines: VS Code / Copilot uses the key servers (not mcpServers); Continue and Goose use YAML (a JSON writer corrupts them); aider has no MCP support at all. Always follow the agent's own current docs. The one thing that works everywhere without any of this is the plain-text path above.

Prefer manual MCP registration? Each host has its own mechanism:

Host	Manual registration
Claude Code	claude mcp add trailmem -- trailmem-mcp
Codex	add an [mcp_servers.trailmem] table to ~/.codex/config.toml
Kiro	add trailmem under mcpServers in ~/.kiro/settings/mcp.json
Kilo	add trailmem under mcp in ~/.config/kilo/kilo.jsonc as {"type":"local","command":["trailmem-mcp"]} (kilo 7.x format)
OpenCode	add trailmem under mcp in ~/.config/opencode/opencode.json
Antigravity	add trailmem under mcpServers in ~/.gemini/config/mcp_config.json
Zed	add trailmem under context_servers in ~/.config/zed/settings.json
Cursor	add trailmem under mcpServers in ~/.cursor/mcp.json
Windsurf	add trailmem under mcpServers in ~/.codeium/windsurf/mcp_config.json

Any other MCP agent

Trailmem works with any agent that speaks MCP — Cursor, Windsurf, Cline, Zed, Gemini CLI, or anything newer. trailmem integrate only automates the hosts above; for everything else, register it yourself. You need exactly three facts:

1. Transport: stdio (no URL, no port, no HTTP).
2. Command: trailmem-mcp — no arguments, no environment variables required.
3. Server name: trailmem (any name works; tool names don't depend on it).

Most agents use a JSON block shaped like this (key name varies — mcpServers, mcp, servers):

{
  "mcpServers": {
    "trailmem": {
      "command": "trailmem-mcp",
      "args": []
    }
  }
}

If the agent can't find the command, use the absolute path — print it with:

which trailmem-mcp        # Windows: where trailmem-mcp

Then restart the agent and check the wiring: the agent should see six trailmem_* tools, and calling trailmem_welcome should return a briefing. trailmem doctor verifies the database side.

Updating

uv tool upgrade trailmem       # if installed with uv
pipx upgrade trailmem          # if installed with pipx
pip install --upgrade trailmem # if installed with pip (inside the venv)

There is no in-app "update available" notice — trailmem sends no telemetry, by design. Watch the GitHub Releases page instead.

The agent then gets six tools: trailmem_welcome (once-per-session briefing), trailmem_store, trailmem_query, trailmem_show, trailmem_edit, trailmem_link. Everything is also available to humans via the trailmem CLI (store, query, show, list, stats, link, archive, ...).

Try it from the CLI (note: content is positional; --agent user for your own notes):

trailmem store --title "First note" --type lesson --agent user "Something worth remembering."
trailmem query "what did I note earlier"
trailmem list
trailmem help                # or: trailmem <command> --help

Why

• Local-first. One SQLite file (~/.trailmem/trailmem.db), WAL mode, no cloud, no daemon. Embeddings run locally via ONNX (default: bge-small-en-v1.5, user-swappable with trailmem model use).
• A graph, not a list. Typed edges (related, supersedes, evolves, contradicts, derived_from), orphan warnings at store time, supersede chains instead of destructive overwrites.
• Token discipline. Context is injected exactly once per session (welcome, ~600–800 tokens). No per-turn injection, ever. Repeat welcomes return a short form.
• No junk memories. 4-band duplicate detection (exact hash reject → >0.92 block → 0.85–0.92 warn → accept), mandatory titles, hard-reject on unattributed stores, no auto-store lifecycle hooks.
• No telemetry. The server writes only what the user needs (e.g. a local hooks.log diagnostic); it never emits analytics — a deliberate anti-goal, not an oversight.

Status

v0.1.0 is live on PyPI. Core implemented and tested: schema, store/dedup, query/show, welcome, MCP server, CLI, hooks, model management, loopback dashboard, host integration. The design contract lives in docs/ — schema, welcome lifecycle, duplicate policy, evolution rules, CLI/MCP surfaces, hooks, seeding playbook, and the dashboard contract.

License

MIT