clinotes

Project memory for AI coding agents — git-native, ~200 tokens to recall, one line to wire as MCP.

AI coding agents forget everything between sessions, so they re-ask and re-decide things you settled last week. clinotes keeps a project's decisions and learnings as plain Markdown in a .clinotes/ folder in your repo. Your agent recalls a compact index (~200 tokens), then pulls the full reasoning for a single entry only when it's relevant.

Because it's just text in the repo, the memory is diffable, reviewable, and your teammate's agent inherits it via git — no database, no embeddings, no server.

Why it's different

 inline comments   →  rot, scattered, not addressable by the agent
 wikis / Notion    →  live OUTSIDE the repo, the agent never reads them
 vector-DB memory  →  infra, embeddings, opaque, not human-readable
 global rules files →  not per-decision, not shared with teammates via git
 ─────────────────────────────────────────────────────────────────────
 clinotes          →  per-repo · git-tracked · plain Markdown · MCP-native
                      L0 index (~200 tok) → L2 detail only when relevant

Install

pip install clinotes

Wire it into your agent (the 30-second path)

Claude Code — one line:

claude mcp add clinotes -- uvx clinotes-mcp

Cursor (.cursor/mcp.json):

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

Now your agent can record decisions/learnings and recall them in any future session — pip install not even required, uvx fetches it on demand.

How it works

Two tiers, so recall stays cheap:

 recall_index   →  the L0 map (~200 tok)   "here's everything we've recorded"
       │                                      ↓ agent picks the relevant id
 recall_detail  →  one L2 entry (full why)  "give me d2's full reasoning"

On disk, in your repo:

 .clinotes/
   INDEX.md          # L0 — titles + ids, grouped by Decisions / Learned
   detail/
     d1.md  d2.md    # L2 — full "why" + alternatives + refs (YAML frontmatter)
     l1.md  l2.md    # full notes for each learning

Commit .clinotes/ with your code and the memory travels with the repo.

Features

• Git-native — plain Markdown + YAML frontmatter. Diffable, reviewable, portable.
• Token-frugal — survey the whole project in ~200 tokens; expand on demand.
• MCP-native — 4 tools (recall_index, recall_detail, note_decision, note_learned).
• Decisions and learnings — capture why we chose X and the gotcha that cost 3 hours, each with refs back to the code.
• No infra — no database, no embeddings, no daemon. Just files.
• Concurrency-safe — cross-process lock + atomic writes, so parallel agents don't clobber the index.
• Human-readable — the same files serve the model and the next engineer.

Python API

from clinotes import note_decision, recall_index, recall_detail

note_decision(
    title="postgres over mysql",
    why="client DBA only supports pg",
    alternatives=["mysql", "sqlite"],
    refs=["infra/db.py"],
)

print(recall_index())          # L0 — cheap survey
print(recall_detail("d1"))     # L2 — full detail

CLI

clinotes init          # scaffold .clinotes/ in the current repo
clinotes ls            # print the index (L0)
clinotes show d1       # print one entry's full detail (L2)

Recording new memory happens through the MCP tools or the Python API; the CLI is for scaffolding and inspecting.

Format

The on-disk layout, ID scheme, and frontmatter spec are defined in SPEC.md.

License

MIT — see LICENSE.