clinotes 0.1.0

Pyramid memory for LLM-driven CLIs. Git-native, MCP-ready.

clinotes

Pyramid memory for LLM-driven CLIs. Git-native, MCP-ready.

What it is

clinotes is project memory that lives in your repo. It stores decisions and learnings as plain Markdown with YAML frontmatter inside a .clinotes/ directory. Because the format is text-first and git-native, any LLM can recall it cheaply without hallucinating your stack.

Why

LLMs forget between sessions. Inline code comments rot. Wikis live outside the repo. clinotes gives your agent a structured, versioned memory layer it can read in ~200 tokens and expand only when needed.

Install

pip install clinotes

Quickstart

clinotes init          # scaffold .clinotes/
clinotes ls            # show the index (L0)
clinotes show d1       # show a detail (L2)

MCP Setup

Add clinotes to your editor so the LLM can recall and record project memory.

Claude Code:

claude mcp add clinotes -- uvx clinotes-mcp

Cursor (.cursor/mcp.json):

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

Python API

from clinotes import note_decision, recall_index, recall_detail

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

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

Format

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