clinotes 0.1.0__tar.gz

clinotes-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.coverage
+htmlcov/
+.clinotes/

clinotes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karthick Raja M
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clinotes-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: clinotes
+Version: 0.1.0
+Summary: Pyramid memory for LLM-driven CLIs. Git-native, MCP-ready.
+Project-URL: Homepage, https://github.com/karthyick/clinotes
+Project-URL: Repository, https://github.com/karthyick/clinotes
+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
+
+> Pyramid memory for LLM-driven CLIs. Git-native, MCP-ready.
+>
+> [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
+
+```bash
+pip install clinotes
+```
+
+## Quickstart
+
+```bash
+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:**
+```bash
+claude mcp add clinotes -- uvx clinotes-mcp
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "clinotes": {
+      "command": "uvx",
+      "args": ["clinotes-mcp"]
+    }
+  }
+}
+```
+
+## Python API
+
+```python
+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](SPEC.md).

clinotes-0.1.0/README.md

@@ -0,0 +1,70 @@
+# clinotes
+
+> Pyramid memory for LLM-driven CLIs. Git-native, MCP-ready.
+>
+> [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
+
+```bash
+pip install clinotes
+```
+
+## Quickstart
+
+```bash
+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:**
+```bash
+claude mcp add clinotes -- uvx clinotes-mcp
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "clinotes": {
+      "command": "uvx",
+      "args": ["clinotes-mcp"]
+    }
+  }
+}
+```
+
+## Python API
+
+```python
+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](SPEC.md).

clinotes-0.1.0/SPEC.md

@@ -0,0 +1,111 @@
+# clinotes Memory Format Specification v0.1
+
+## Overview
+
+The clinotes memory format is a plain-text, git-native project knowledge base. It lives in a `.clinotes/` directory at the project root and is designed for cheap LLM recall through a two-level pyramid model.
+
+## Directory Layout
+
+```
+.clinotes/
+├── INDEX.md              # L0 — compact index of all memory IDs
+└── detail/
+    ├── d1.md             # L2 — full detail, one file per memory
+    ├── d2.md
+    ├── l1.md
+    └── ...
+```
+
+## ID Scheme
+
+- **Decisions**: `d{n}` (e.g., `d1`, `d2`)
+- **Learnings**: `l{n}` (e.g., `l1`, `l2`)
+- `n` starts at 1 and is monotonic per prefix.
+
+## INDEX.md Format
+
+```markdown
+# Project Memory Index
+
+## Decisions
+
+- d1: postgres over mysql
+
+## Learned
+
+- l1: asyncpg caches prepared statements
+
+## Rejected
+
+## Open
+```
+
+Rules:
+- The first line is always `# Project Memory Index`.
+- The four section headers (`## Decisions`, `## Learned`, `## Rejected`, `## Open`) always exist, in that order, even when empty.
+- Each entry line is exactly `- {id}: {title}`.
+- `Rejected` and `Open` are reserved for forward compatibility.
+
+## detail/{id}.md Format
+
+Every detail file uses YAML frontmatter followed by a markdown body.
+
+### Decision
+
+```markdown
+---
+id: d1
+type: decision
+title: postgres over mysql
+created: 2026-05-30T14:23:01+00:00
+refs:
+  - infra/db.py
+---
+
+## Why
+
+client DBA only supports pg
+
+## Alternatives
+
+- mysql
+- sqlite
+```
+
+### Learned
+
+```markdown
+---
+id: l1
+type: learned
+title: asyncpg caches prepared statements
+created: 2026-05-30T14:25:10+00:00
+refs: []
+---
+
+## Notes
+
+Neon's pgbouncer breaks asyncpg statement cache; set statement_cache_size=0.
+```
+
+Rules:
+- `created` is ISO-8601 with timezone.
+- `refs` is always a YAML list; may be empty (`[]`).
+- Decision body: `## Why` followed by the rationale. If alternatives are provided, `## Alternatives` follows with a `- {item}` list.
+- Learned body: `## Notes` followed by the note text.
+
+## The L0 / L2 Pyramid Recall Model
+
+LLM context is expensive and finite. clinotes uses a two-tier pyramid to minimize token spend during project recall:
+
+- **L0 (INDEX.md)**: ~200 tokens. A dense, structured list of every decision and learning. This is the "table of contents" for project memory. An LLM should read this first to locate relevant IDs.
+- **L2 (detail/{id}.md)**: ~400 tokens per file. The full rationale, alternatives, and references for a single memory. An LLM reads only the specific IDs it needs after scanning L0.
+
+Why this saves context:
+- A project with 20 memories costs ~200 tokens to survey at L0, versus ~8,000 tokens if every detail were inlined.
+- The index gives the LLM a searchable map; details give precision without noise.
+- Because the format is plain Markdown with YAML frontmatter, it diffs cleanly in git and merges predictably.
+
+---
+
+This specification is implementation-neutral. Any tool that reads and writes this exact on-disk layout is compatible.

clinotes-0.1.0/conftest.py

@@ -0,0 +1,2 @@
+import sys, pathlib
+sys.path.insert(0, str(pathlib.Path(__file__).parent / "src"))

clinotes-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "clinotes"
+version = "0.1.0"
+description = "Pyramid memory for LLM-driven CLIs. Git-native, MCP-ready."
+authors = [
+    { name = "Karthick Raja M", email = "Karthickrajam18@gmail.com" },
+]
+requires-python = ">=3.10"
+readme = "README.md"
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+keywords = ["mcp", "memory", "llm", "cli", "agent"]
+dependencies = [
+    "pydantic>=2",
+    "typer>=0.12",
+    "python-frontmatter>=1.0",
+    "pyyaml>=6.0",
+    "fastmcp>=3.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "black", "build"]
+
+[project.scripts]
+clinotes = "clinotes.cli:app"
+clinotes-mcp = "clinotes.server:main"
+
+[project.urls]
+Homepage = "https://github.com/karthyick/clinotes"
+Repository = "https://github.com/karthyick/clinotes"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clinotes"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

clinotes-0.1.0/src/clinotes/__init__.py

@@ -0,0 +1,15 @@
+"""Clinotes - CLI-driven memory for AI-assisted development.
+
+A simple system for capturing and retrieving decisions and learnings
+during development, optimized for LLM-driven workflows.
+"""
+from .api import recall_index, recall_detail, note_decision, note_learned
+
+__version__ = "0.1.0"
+__all__ = [
+    "recall_index",
+    "recall_detail",
+    "note_decision",
+    "note_learned",
+    "__version__",
+]

clinotes-0.1.0/src/clinotes/api.py

@@ -0,0 +1,211 @@
+"""Public API for clinotes memory management.
+
+Provides functions to record and recall decisions and learnings. Frontmatter is
+serialized with a real YAML dumper so titles/refs containing colons, quotes,
+brackets, unicode, or trailing spaces round-trip losslessly.
+"""
+from datetime import datetime, timezone
+import os
+import re
+from pathlib import Path
+
+import yaml
+
+from . import storage, ids, index, schema
+
+# A valid memory id is a letter-prefix followed by digits (e.g. "d1", "l12").
+# Anything else is rejected so recall_detail cannot be coerced into a path
+# traversal (e.g. "../../secret").
+_ID_RE = re.compile(r"^[A-Za-z]+[0-9]+$")
+
+
+def _root() -> Path:
+    """Return the clinotes memory root directory.
+
+    Resolves from the ``CLINOTES_ROOT`` environment variable, defaulting to
+    ``.clinotes`` in the current working directory.
+    """
+    return Path(os.environ.get("CLINOTES_ROOT", ".clinotes"))
+
+
+def _validate_title(title: str) -> str:
+    """Validate a memory title.
+
+    Args:
+        title: The proposed title.
+
+    Returns:
+        The title unchanged.
+
+    Raises:
+        ValueError: If the title is empty/blank or contains a line break
+            (titles are single-line labels — a newline would corrupt the
+            single-line INDEX.md entry).
+    """
+    if not title or not title.strip():
+        raise ValueError("title must not be empty or blank")
+    if "\n" in title or "\r" in title:
+        raise ValueError("title must be a single line (no line breaks)")
+    return title
+
+
+def recall_index() -> str:
+    """L0: return INDEX.md text.
+
+    Calls :func:`index.ensure_index` first so a fresh project returns the empty
+    scaffold rather than raising.
+
+    Returns:
+        The full text of the INDEX.md file.
+    """
+    root = _root()
+    index.ensure_index(root)
+    return storage.read_file(root / "INDEX.md")
+
+
+def recall_detail(id: str) -> str:
+    """L2: return full text of ``_root()/detail/{id}.md``.
+
+    Args:
+        id: The memory identifier (e.g., ``"d1"``, ``"l3"``).
+
+    Returns:
+        The full markdown text of the detail file.
+
+    Raises:
+        ValueError: If ``id`` is malformed or no memory exists with that id.
+    """
+    if not isinstance(id, str) or not _ID_RE.match(id):
+        raise ValueError(f"No memory with id={id}")
+    detail_path = _root() / "detail" / f"{id}.md"
+    if not detail_path.exists():
+        raise ValueError(f"No memory with id={id}")
+    return storage.read_file(detail_path)
+
+
+def _render_detail(
+    id: str,
+    type: str,
+    title: str,
+    body: str,
+    alternatives: list[str],
+    refs: list[str],
+) -> str:
+    """Render the full markdown document (YAML frontmatter + body).
+
+    The frontmatter is produced with :func:`yaml.safe_dump` so any special
+    characters (``:``, quotes, ``[``/``{``, ``#``, unicode, trailing spaces)
+    are correctly escaped and round-trip via ``frontmatter.loads``.
+
+    Args:
+        id: Unique identifier (e.g., ``"d1"``).
+        type: Either ``"decision"`` or ``"learned"``.
+        title: Human-readable single-line title.
+        body: The "why" for decisions, the "notes" text for learnings.
+        alternatives: Alternatives (decisions only; emitted only if non-empty).
+        refs: File/URL references (emitted as a YAML list).
+
+    Returns:
+        The complete markdown document.
+
+    Raises:
+        ValueError: If ``type`` is not a known memory type.
+    """
+    if type not in schema.ALLOWED_TYPES:
+        raise ValueError(f"Unknown type: {type}")
+
+    meta = {
+        "id": id,
+        "type": type,
+        "title": title,
+        "created": datetime.now(timezone.utc).isoformat(),
+        "refs": list(refs),
+    }
+    fm = yaml.safe_dump(
+        meta, sort_keys=False, allow_unicode=True, default_flow_style=False
+    ).strip()
+    frontmatter_block = f"---\n{fm}\n---"
+
+    if type == "decision":
+        parts = [frontmatter_block, "", "## Why", "", body]
+        if alternatives:
+            alt_lines = "\n".join(f"- {alt}" for alt in alternatives)
+            parts.extend(["", "## Alternatives", "", alt_lines])
+        return "\n".join(parts)
+
+    # learned
+    return "\n".join([frontmatter_block, "", "## Notes", "", body])
+
+
+def note_decision(
+    title: str,
+    why: str,
+    alternatives: list[str] | None = None,
+    refs: list[str] | None = None,
+) -> str:
+    """Record a decision.
+
+    Args:
+        title: Single-line title (must not be empty/blank or contain newlines).
+        why: Explanation of the decision.
+        alternatives: Optional alternatives considered.
+        refs: Optional file/URL references.
+
+    Returns:
+        The new id (e.g., ``"d3"``).
+
+    Raises:
+        ValueError: If the title is invalid.
+    """
+    _validate_title(title)
+    root = _root()
+    # Serialize id-assignment + detail-write + index-update so concurrent
+    # writers in the same .clinotes dir can't collide on ids or lose entries.
+    with storage.lock(root):
+        new_id = ids.next_id(root, "d")
+        content = _render_detail(
+            id=new_id,
+            type="decision",
+            title=title,
+            body=why,
+            alternatives=alternatives or [],
+            refs=refs or [],
+        )
+        storage.write_file_atomic(root / "detail" / f"{new_id}.md", content)
+        index.update_index(root, "Decisions", new_id, title)
+    return new_id
+
+
+def note_learned(
+    title: str,
+    body: str,
+    refs: list[str] | None = None,
+) -> str:
+    """Record a learning.
+
+    Args:
+        title: Single-line title (must not be empty/blank or contain newlines).
+        body: The notes/learning content.
+        refs: Optional file/URL references.
+
+    Returns:
+        The new id (e.g., ``"l3"``).
+
+    Raises:
+        ValueError: If the title is invalid.
+    """
+    _validate_title(title)
+    root = _root()
+    with storage.lock(root):
+        new_id = ids.next_id(root, "l")
+        content = _render_detail(
+            id=new_id,
+            type="learned",
+            title=title,
+            body=body,
+            alternatives=[],
+            refs=refs or [],
+        )
+        storage.write_file_atomic(root / "detail" / f"{new_id}.md", content)
+        index.update_index(root, "Learned", new_id, title)
+    return new_id

clinotes-0.1.0/src/clinotes/cli.py

@@ -0,0 +1,41 @@
+"""Typer CLI for clinotes memory management.
+
+Provides commands to initialize, list, and show project memory entries.
+"""
+from pathlib import Path
+
+import typer
+
+from . import api, index
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Pyramid memory for LLM-driven CLIs.",
+)
+
+
+@app.command()
+def init() -> None:
+    """Create .clinotes/ in the current directory (idempotent)."""
+    root = api._root()
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "detail").mkdir(parents=True, exist_ok=True)
+    index.ensure_index(root)
+    typer.echo(f"initialized .clinotes/ at {root.resolve()}")
+
+
+@app.command()
+def show(id: str) -> None:
+    """Print the full detail for a memory id (e.g. clinotes show d2)."""
+    try:
+        detail = api.recall_detail(id)
+    except ValueError:
+        typer.echo(f"No memory with id={id}", err=True)
+        raise typer.Exit(1)
+    typer.echo(detail)
+
+
+@app.command()
+def ls() -> None:
+    """Print the INDEX (all ids grouped by section)."""
+    typer.echo(api.recall_index())

clinotes-0.1.0/src/clinotes/ids.py

@@ -0,0 +1,37 @@
+from pathlib import Path
+
+
+def next_id(root: Path, prefix: str) -> str:
+    """Return the next id for a prefix, e.g. 'd3' or 'l7'.
+
+    Scans root/'detail' for files named '{prefix}{n}.md', finds the max n,
+    returns f'{prefix}{max_n + 1}'. Returns f'{prefix}1' when none exist.
+    Only counts files whose stem is prefix followed by digits (ignore others).
+
+    Args:
+        root: The project root directory containing the ``.clinotes`` tree.
+        prefix: The id prefix character(s), e.g. ``"d"`` or ``"l"``.
+
+    Returns:
+        The next monotonic id string for the given prefix.
+    """
+    detail = root / "detail"
+    max_n = 0
+    if detail.exists() and detail.is_dir():
+        for item in detail.iterdir():
+            if not item.is_file():
+                continue
+            if item.suffix != ".md":
+                continue
+            stem = item.stem
+            if not stem.startswith(prefix):
+                continue
+            suffix = stem[len(prefix) :]
+            if not suffix.isdigit():
+                continue
+            n = int(suffix)
+            if n > max_n:
+                max_n = n
+    if max_n == 0:
+        return f"{prefix}1"
+    return f"{prefix}{max_n + 1}"