Mindtrail

🧭 Mindtrail

Leave a trail your AI agents can follow.

Persistent, local-first memory for coding agents over MCP. Tell your agent something once, and every future session remembers it.

Install · Day to day · How it works · Benchmarks · Docs

---

Every new agent session starts from zero. You explain your conventions again, re-state your preferences, and re-describe decisions you made last week. Mindtrail gives your agents a shared, long-term memory through the Model Context Protocol, so what one session learns, every later session (in any tool) can recall.

• 🔌 Works with any MCP client. One memory shared by Claude Code, Claude Desktop, Cursor, VS Code, Codex and your own agents.
• 🏠 Local-first and private. One SQLite file on your machine. No account, no API key, no telemetry.
• ⚡ One command to install. Published on PyPI and the official MCP Registry; with uv there is nothing to install first.
• 🗂️ Scoped automatically. Repo facts stay with the repo (detected from the git remote) and personal preferences follow you everywhere.
• 🔎 Hybrid retrieval. Keyword (BM25) and vector search, fused and ranked, with the ranking signals shown for every result.
• 🛡️ Safe by default. Refuses to store credentials, marks recalled memory as untrusted data, and deletes for real.

Does it actually help?

We tested it with real Claude Code sessions. In one session the user mentions a project fact in passing ("FYI, this project uses pnpm"). A fresh session later gets a task that depends on it ("how do I add lodash?"). The agent is never told to use Mindtrail.

Without memory, the agent answers from habit every time: npm install lodash, a commit message in the wrong format, port 5432 instead of your 5433. With Mindtrail it checks first and gets your project's answer. This is a small test (12 facts run three times, one model, an empty repository), not a measure of task success on large codebases. Method, raw results and how to reproduce.

Install

Mindtrail needs Python 3.11+. The fastest route is uv: uvx downloads and runs Mindtrail on demand, so you only add it to your client. The first time the server starts, it downloads the embedding model (~210 MB) in the background.

Claude Code

claude mcp add mindtrail --scope user -- uvx --from "mindtrail[semantic]" mindtrail serve

--scope user makes Mindtrail available in every project. Check it with claude mcp list.

Cursor and VS Code

Claude Desktop, Windsurf and other JSON-configured clients

Add this to the client's MCP config (in Claude Desktop: Settings → Developer → Edit Config):

{

"mcpServers": { "mindtrail": { "command": "uvx", "args": ["--from", "mindtrail[semantic]", "mindtrail", "serve"] } } }

Codex

# ~/.codex/config.toml

[mcp_servers.mindtrail] command = "uvx" args = ["--from", "mindtrail[semantic]", "mindtrail", "serve"]

Without uv

Install the CLI once with pipx (or pip), then point your client at mindtrail serve:

pipx install "mindtrail[semantic]"

mindtrail init # downloads the model now and prints client configs claude mcp add mindtrail --scope user -- mindtrail serve # Claude Code

Want the smallest install? Drop [semantic]: Mindtrail then needs no model download and matches on words instead of meaning (see Better semantic recall). More clients and troubleshooting are in [docs/integrations.md](https://github.com/RohitDeshmukh-1/Mindtrail-MCP/blob/main/docs/integrations.md).

Try it

Session 1 › FYI, this project uses conventional commits and squash merges.

Session 2 › Write a commit message for these changes. → the agent recalls the convention and writes "feat(api): add pagination to /orders"

Upgrading

uvx picks up new releases on its own (uvx --refresh ... forces a check). With pipx, run pipx upgrade mindtrail. Your memories live in ~/.mindtrail and are kept across upgrades. See the changelog for what changed.

Using it day to day

You don't need special commands. Work as usual and the agent decides what to keep:

• Mention things once. "We deploy from the release branch", "I prefer pytest over unittest", "the flaky test was a timezone bug, fixed by pinning TZ=UTC". The agent stores facts like these on its own. Say "remember that…" when you want to be sure.
• Project vs. personal. Facts about the repository go to a project space, shared by every clone of the same git remote. Facts about you ("I like short answers") go to your personal space and apply in every project.
• Things change. Say "we moved from npm to pnpm" and the agent replaces the old memory instead of keeping both. The old one is kept as history but no longer recalled.
• Ask what it knows. "What do you remember about this project?" or, from the terminal, mindtrail list and mindtrail recall " ".
• Forget anything. "Forget the staging URL" in chat, or mindtrail forget . Deletes are permanent.
• Switch tools freely. Claude Code, Cursor and Codex pointed at the same Mindtrail share one memory, so a convention taught in one tool is known in all of them.

Good things to store: conventions, commands, ownership, where config lives, decisions and why they were made, root causes of tricky bugs. Don't bother with what the code or git history already says. Secrets are refused automatically.

How it works

Your agent gets three tools, and Mindtrail's server instructions tell it when to use them:

Set MINDTRAIL_TOOLS=full for four more: search_memory (filters by space, type and validity), get_context (a prompt-ready block within a token budget), update_memory (edits with version history) and get_memory.

Behind the tools is a small, well-tested engine: duplicate merging, supersession, validity windows, version history and hybrid ranking. See [docs/architecture.md](https://github.com/RohitDeshmukh-1/Mindtrail-MCP/blob/main/docs/architecture.md).

Manage memory from the terminal

mindtrail recall "how do we deploy?"   # search project + personal memory

mindtrail remember "Staging is at staging.example.com" --scope project mindtrail list # newest first mindtrail forget # permanent delete mindtrail export -o memories.jsonl # everything you've stored, as JSON Lines mindtrail doctor # diagnose the install

Better semantic recall

The default embedder matches on words and word fragments. For recall by meaning ("how do we deploy?" → "deploys go through GitHub Actions"), install the local neural model. It runs on CPU and needs no API key:

pipx install "mindtrail[semantic]"   # or use the uvx config above

mindtrail init # downloads the model once (~210 MB) and re-indexes existing memories

For a smaller download (67 MB, somewhat lower recall), set MINDTRAIL_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5. Memories stored under another model are re-embedded automatically the next time the server starts.

Retrieval benchmark

The agent test is in Does it actually help?. On two held-out sets of developer-memory questions (82 in total) that were never used for tuning (methodology):

This is a small, synthetic retrieval benchmark written by us. Run mindtrail bench to reproduce it, or add your own dataset.

Use it from Python

from mindtrail import MemoryService

memory = MemoryService.from_config() memory.remember("The API uses FastAPI and PostgreSQL", space_id="project:shop") print(memory.get_context("add a new endpoint", space_ids=["project:shop"]).text)

Privacy and security

Everything stays in ~/.mindtrail/mindtrail.db on your machine. Mindtrail refuses writes that look like API keys, tokens or private keys. forget overwrites deleted data on disk, and recalled memories are marked as untrusted reference data so agents don't follow instructions stored inside them. See SECURITY.md to report issues.

Roadmap

• Core engine: hybrid retrieval, dedup, supersession, validity windows, history
• MCP server and CLI, with automatic project scoping
• Retrieval benchmark suite in CI (recall@k, MRR, abstention, leak rate)
• Published on PyPI and the official MCP Registry (v0.1.0)
• PostgreSQL + pgvector backend with multi-tenant isolation
• Hosted remote MCP with one-click OAuth connectors
• Web memory viewer (browse, edit, delete, export)
• Entity graph, contradiction detection and memory consolidation

Contributing

Issues and PRs are welcome. Read CONTRIBUTING.md to get set up; the whole suite runs in about 15 seconds. If Mindtrail saves you from re-explaining your codebase, a ⭐ helps others find it.

License

MIT