Metadata-Version: 2.4
Name: clinotes
Version: 0.1.1
Summary: Project memory for AI coding agents - git-native, MCP-ready. Decisions + learnings as Markdown in your repo.
Project-URL: Homepage, https://github.com/karthyick/clinotes
Project-URL: Repository, https://github.com/karthyick/clinotes
Project-URL: Issues, https://github.com/karthyick/clinotes/issues
Project-URL: Documentation, https://github.com/karthyick/clinotes#readme
Author-email: Karthick Raja M <Karthickrajam18@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,cli,llm,mcp,memory
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fastmcp>=3.0
Requires-Dist: pydantic>=2
Requires-Dist: python-frontmatter>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# clinotes

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

[![PyPI version](https://img.shields.io/pypi/v/clinotes.svg)](https://pypi.org/project/clinotes/)
[![Python versions](https://img.shields.io/pypi/pyversions/clinotes.svg)](https://pypi.org/project/clinotes/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-ready-8b5cf6.svg)](https://modelcontextprotocol.io/)

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

```bash
pip install clinotes
```

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

**Claude Code** — one line:

```bash
claude mcp add clinotes -- uvx clinotes-mcp
```

**Cursor** (`.cursor/mcp.json`):

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

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

```bash
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](SPEC.md).

## License

MIT — see [LICENSE](LICENSE).
