Metadata-Version: 2.4
Name: trailmem
Version: 0.1.4
Summary: Local-first, graph-linked persistent memory for AI coding agents (MCP server + CLI)
Project-URL: Homepage, https://github.com/amit/trailmem
Author-email: Amit Kushwaha <amitkushwaha2805@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,knowledge-graph,mcp,memory,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: mcp
Requires-Dist: numpy
Requires-Dist: onnxruntime
Requires-Dist: orjson
Requires-Dist: sqlite-vec<0.2.0
Requires-Dist: tokenizers
Description-Content-Type: text/markdown

# trailmem

[![PyPI](https://img.shields.io/pypi/v/trailmem)](https://pypi.org/project/trailmem/)
[![Python](https://img.shields.io/pypi/pyversions/trailmem)](https://pypi.org/project/trailmem/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**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`](https://docs.astral.sh/uv/), a standalone binary that needs **no pre-installed Python** (it fetches one for you):

```bash
# 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`](https://pipx.pypa.io/)? `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>

```bash
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

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

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`):

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

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

```bash
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

```bash
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):

```bash
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](https://pypi.org/project/trailmem/). 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/`](docs/index.md) — schema, welcome lifecycle, duplicate policy, evolution rules, CLI/MCP surfaces, hooks, seeding playbook, and the dashboard contract.

## License

MIT
