trailmem 0.1.5

Local-first, graph-linked persistent memory for AI coding agents (MCP server + CLI)

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).

Plain pip (only inside a virtualenv or CI)

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.

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. Three things guard against that:

• /tm-save (Claude Code) — tell the still-running agent to store this session's decisions, lessons, and open tasks. Run it before /exit.
• Statusline — trailmem statusline prints 🧠 trailmem: N saved this session, or ⚠ 0 saved · /tm-save before exit when nothing has been captured yet. Wire it into your host's statusline for an always-visible count.
• Next-session flag — if the previous session stored nothing, the next welcome opens with a loud reminder.

Prefer manual 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