clinotes 0.1.0__py3-none-any.whl

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/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/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/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}"

clinotes/index.py

@@ -0,0 +1,103 @@
+"""Index management for clinotes memory.
+
+Manages the INDEX.md file which provides a flat list of all memory entries
+grouped by section. INDEX.md is always rendered deterministically: a title
+line, then each section in :data:`SECTIONS` order, with a single blank line
+separating a section's entries from the following header and a single
+trailing newline at end-of-file.
+"""
+from pathlib import Path
+
+from . import storage
+
+SECTIONS = ("Decisions", "Learned", "Rejected", "Open")
+
+_TITLE = "# Project Memory Index"
+
+
+def _render(entries: dict[str, list[str]]) -> str:
+    """Render the full INDEX.md text from a section -> entry-lines mapping.
+
+    Args:
+        entries: Mapping of each section name in :data:`SECTIONS` to the list
+            of its entry lines (e.g. ``["- d1: alpha", "- d2: gamma"]``).
+
+    Returns:
+        The complete INDEX.md document with a single trailing newline. Entries
+        within a section are contiguous; exactly one blank line separates the
+        last entry of a section from the next ``## `` header.
+    """
+    blocks = [_TITLE]
+    for name in SECTIONS:
+        section_entries = entries.get(name, [])
+        if section_entries:
+            blocks.append(f"## {name}\n\n" + "\n".join(section_entries))
+        else:
+            blocks.append(f"## {name}")
+    return "\n\n".join(blocks) + "\n"
+
+
+def _parse(content: str) -> dict[str, list[str]]:
+    """Parse INDEX.md text into a section -> entry-lines mapping.
+
+    Recovers entries regardless of the prior blank-line layout, so the file
+    can always be re-rendered cleanly.
+
+    Args:
+        content: Raw INDEX.md text.
+
+    Returns:
+        Mapping of each section name in :data:`SECTIONS` to its entry lines.
+    """
+    entries: dict[str, list[str]] = {name: [] for name in SECTIONS}
+    current: str | None = None
+    for raw in content.replace("\r\n", "\n").splitlines():
+        line = raw.rstrip()
+        if line.startswith("## "):
+            heading = line[3:].strip()
+            current = heading if heading in entries else None
+        elif line.startswith("- ") and current is not None:
+            entries[current].append(line)
+    return entries
+
+
+def ensure_index(root: Path) -> None:
+    """Create ``root/INDEX.md`` with the title and four empty section headers.
+
+    Idempotent: does nothing if the file already exists. Creates ``root`` if
+    needed.
+
+    Args:
+        root: The ``.clinotes`` directory.
+    """
+    index_path = root / "INDEX.md"
+    if index_path.exists():
+        return
+    root.mkdir(parents=True, exist_ok=True)
+    storage.write_file_atomic(index_path, _render({name: [] for name in SECTIONS}))
+
+
+def update_index(root: Path, section: str, id: str, title: str) -> None:
+    """Append ``- {id}: {title}`` under the ``## {section}`` header.
+
+    Calls :func:`ensure_index` first, parses the existing index, appends the
+    new entry as the last line of the target section, then re-renders the whole
+    file deterministically.
+
+    Args:
+        root: The ``.clinotes`` directory.
+        section: One of :data:`SECTIONS` (e.g. ``"Decisions"``).
+        id: The memory id (e.g. ``"d3"``).
+        title: The memory title.
+
+    Raises:
+        ValueError: If ``section`` is not in :data:`SECTIONS`.
+    """
+    if section not in SECTIONS:
+        raise ValueError(f"Invalid section: {section!r}. Must be one of {SECTIONS}")
+
+    ensure_index(root)
+    index_path = root / "INDEX.md"
+    entries = _parse(storage.read_file(index_path))
+    entries[section].append(f"- {id}: {title}")
+    storage.write_file_atomic(index_path, _render(entries))

clinotes/schema.py

@@ -0,0 +1,61 @@
+"""Schema definitions for clinotes memory frontmatter validation."""
+
+from datetime import datetime
+from pydantic import BaseModel, field_validator
+
+ALLOWED_TYPES = ("decision", "learned")
+
+
+class MemoryDetail(BaseModel):
+    """Represents the validated frontmatter for a memory entry.
+
+    Attributes:
+        id: Unique identifier (e.g., 'd1', 'l3').
+        type: Either 'decision' or 'learned'.
+        title: Human-readable title (non-empty, non-blank).
+        created: ISO-8601 datetime with timezone.
+        refs: Optional list of file references.
+    """
+
+    id: str
+    type: str
+    title: str
+    created: datetime
+    refs: list[str] = []
+
+    @field_validator("type")
+    @classmethod
+    def validate_type(cls, v: str) -> str:
+        """Ensure type is one of ALLOWED_TYPES."""
+        if v not in ALLOWED_TYPES:
+            raise ValueError(f"type must be one of {ALLOWED_TYPES}, got '{v}'")
+        return v
+
+    @field_validator("title")
+    @classmethod
+    def validate_title(cls, v: str) -> str:
+        """Ensure title is not empty or blank."""
+        if not v or not v.strip():
+            raise ValueError("title must not be empty or blank")
+        return v
+
+
+def validate_frontmatter(meta: dict) -> MemoryDetail:
+    """Validate a frontmatter dict and return a MemoryDetail.
+
+    Args:
+        meta: Dictionary containing frontmatter keys ('id', 'type', 'title', 'created').
+
+    Returns:
+        A validated MemoryDetail instance.
+
+    Raises:
+        ValueError: If required keys are missing, if type is not in ALLOWED_TYPES,
+            or if title is empty/blank.
+    """
+    required_keys = ("id", "type", "title", "created")
+    for key in required_keys:
+        if key not in meta:
+            raise ValueError(f"missing required frontmatter key: '{key}'")
+
+    return MemoryDetail(**meta)

clinotes/server.py

@@ -0,0 +1,107 @@
+"""FastMCP server wrapper for clinotes.
+
+This module exposes the clinotes memory management tools via MCP protocol.
+Run with: python -m clinotes.server
+"""
+from fastmcp import FastMCP
+
+from . import api
+from . import __version__
+
+app = FastMCP("clinotes", version=__version__)
+
+
+@app.tool()
+def recall_index() -> str:
+    """Read the project memory index (L0).
+
+    Call this FIRST for any project — it returns the compact INDEX.md file
+    listing all decision and learning IDs with their titles. This is cheap
+    (~200 tokens) and gives you the map of available memories before diving
+    into details.
+
+    Returns:
+        The full text of the INDEX.md file containing all recorded decisions
+        and learnings with their IDs and titles.
+    """
+    return api.recall_index()
+
+
+@app.tool()
+def recall_detail(id: str) -> str:
+    """Read full L2 detail for one memory ID.
+
+    Use this after recall_index identifies a relevant ID (e.g., 'd2', 'l3').
+    It returns the complete markdown document including YAML frontmatter
+    (id, type, title, created, refs) and the detailed body (Why for decisions,
+    Notes for learnings).
+
+    Args:
+        id: The memory identifier to retrieve, e.g. 'd1', 'd2', 'l1'.
+
+    Returns:
+        The full markdown text of the detail file including frontmatter
+        and body sections.
+
+    Raises:
+        ValueError: If no memory exists with the given id.
+    """
+    return api.recall_detail(id)
+
+
+@app.tool()
+def note_decision(
+    title: str,
+    why: str,
+    alternatives: list[str] | None = None,
+    refs: list[str] | None = None,
+) -> str:
+    """Record a new decision in the project memory.
+
+    Call this when you make a design choice, architectural decision, or
+    any explicit selection among alternatives. The system assigns the
+    next available decision ID (d1, d2, ...) and persists the full detail.
+
+    Args:
+        title: A concise title describing the decision (required, non-empty).
+        why: The reasoning behind this decision (the 'why' explanation).
+        alternatives: Optional list of alternative options that were considered.
+        refs: Optional list of file paths or URLs referenced in the decision.
+
+    Returns:
+        The newly assigned decision ID, e.g. 'd3'.
+    """
+    return api.note_decision(title, why, alternatives, refs)
+
+
+@app.tool()
+def note_learned(
+    title: str,
+    body: str,
+    refs: list[str] | None = None,
+) -> str:
+    """Record a new learning in the project memory.
+
+    Call this when you discover something worth remembering — a workaround,
+    gotcha, performance insight, or any knowledge gained during development.
+    The system assigns the next available learning ID (l1, l2, ...) and
+    persists the complete detail.
+
+    Args:
+        title: A concise title describing what was learned (required, non-empty).
+        body: The learning or notes content (what was discovered).
+        refs: Optional list of file paths or URLs related to this learning.
+
+    Returns:
+        The newly assigned learning ID, e.g. 'l3'.
+    """
+    return api.note_learned(title, body, refs)
+
+
+def main() -> None:
+    """Run the FastMCP server."""
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

clinotes/storage.py

@@ -0,0 +1,132 @@
+"""Storage layer for clinotes file IO.
+
+Provides atomic file writes (readers never see a partial file) and a small
+cross-process advisory lock so concurrent writers in the same ``.clinotes``
+directory don't lose updates or collide on ids.
+"""
+from contextlib import contextmanager
+from pathlib import Path
+import os
+import tempfile
+import time
+
+# Windows raises these transiently when another process (a second writer, an
+# antivirus scanner, or the search indexer) momentarily holds the target during
+# os.replace. They clear within milliseconds, so we retry rather than fail.
+_WIN_TRANSIENT = (5, 32)  # ERROR_ACCESS_DENIED, ERROR_SHARING_VIOLATION
+_REPLACE_ATTEMPTS = 20
+_REPLACE_BACKOFF = 0.02  # seconds, linear-ish
+
+
+def read_file(path: Path) -> str:
+    """Return file text (utf-8). '' if the file is empty.
+
+    Retries on transient Windows sharing errors so a reader that lands exactly
+    while another process is replacing the file doesn't spuriously fail.
+
+    Raises:
+        FileNotFoundError: If the path does not exist.
+    """
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+    last_exc: Exception | None = None
+    for attempt in range(_REPLACE_ATTEMPTS):
+        try:
+            return path.read_text(encoding="utf-8")
+        except (PermissionError, OSError) as exc:
+            if getattr(exc, "winerror", None) not in _WIN_TRANSIENT:
+                raise
+            last_exc = exc
+            time.sleep(_REPLACE_BACKOFF * (attempt + 1))
+    raise last_exc  # type: ignore[misc]
+
+
+def _atomic_replace(temp_path: str, path: Path) -> None:
+    """os.replace with bounded retry on transient Windows sharing errors."""
+    last_exc: Exception | None = None
+    for attempt in range(_REPLACE_ATTEMPTS):
+        try:
+            os.replace(temp_path, path)
+            return
+        except (PermissionError, OSError) as exc:
+            winerror = getattr(exc, "winerror", None)
+            # Only retry the known-transient Windows cases; re-raise anything else.
+            if winerror not in _WIN_TRANSIENT:
+                raise
+            last_exc = exc
+            time.sleep(_REPLACE_BACKOFF * (attempt + 1))
+    # Exhausted retries — surface the real error.
+    raise last_exc  # type: ignore[misc]
+
+
+def write_file_atomic(path: Path, content: str) -> None:
+    """Atomically write content (utf-8) to ``path``.
+
+    Creates parent directories, writes to a uniquely-named temp file in the
+    same directory, then ``os.replace`` (retried on transient Windows sharing
+    violations) onto the target so readers never see a partial file.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_path = tempfile.mkstemp(dir=path.parent, suffix=".tmp", text=True)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        _atomic_replace(temp_path, path)
+    except BaseException:
+        if os.path.exists(temp_path):
+            try:
+                os.unlink(temp_path)
+            except OSError:
+                pass
+        raise
+
+
+@contextmanager
+def lock(root: Path, timeout: float = 15.0, stale: float = 60.0):
+    """Cross-process advisory lock for the given ``.clinotes`` root.
+
+    Serializes the read-modify-write critical section (id assignment + detail
+    write + index update) so concurrent writers can't collide on ids or lose
+    INDEX.md entries. Uses an exclusive lock file; a lock older than ``stale``
+    seconds is assumed orphaned and reclaimed.
+
+    Args:
+        root: The ``.clinotes`` directory.
+        timeout: Max seconds to wait for the lock before raising TimeoutError.
+        stale: Age in seconds after which an existing lock is treated as orphaned.
+
+    Raises:
+        TimeoutError: If the lock cannot be acquired within ``timeout``.
+    """
+    root.mkdir(parents=True, exist_ok=True)
+    lock_path = root / ".clinotes.lock"
+    deadline = time.monotonic() + timeout
+    acquired = False
+    while True:
+        try:
+            fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            try:
+                os.write(fd, str(os.getpid()).encode())
+            finally:
+                os.close(fd)
+            acquired = True
+            break
+        except FileExistsError:
+            # Reclaim an orphaned lock left by a crashed process.
+            try:
+                if time.time() - os.path.getmtime(lock_path) > stale:
+                    os.unlink(lock_path)
+                    continue
+            except FileNotFoundError:
+                continue  # released between checks — retry immediately
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Could not acquire clinotes lock at {lock_path}")
+            time.sleep(0.02)
+    try:
+        yield
+    finally:
+        if acquired:
+            try:
+                os.unlink(lock_path)
+            except FileNotFoundError:
+                pass

clinotes-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+clinotes/__init__.py,sha256=o8XzDYfDQM35sttCoozIxJAyQD2geQaFIMMbf_vlnSY,418
+clinotes/api.py,sha256=kGhUPLujd4jMJBwoRJ6V6tPYIHozsuL_4DPY_ldffeo,6443
+clinotes/cli.py,sha256=cqUf3405x04SJfWKr_FBUPmzPnBxFq6XUEkuRzujays,1064
+clinotes/ids.py,sha256=-j_bEcGRXgUT4Mi5tBDCUWy0GwnIDuOAIEshewzIGe8,1243
+clinotes/index.py,sha256=wF6d8EHtwPiUsWJ9Nx0z6vFrbFMh3NqlEtJgoVtSBXc,3685
+clinotes/schema.py,sha256=lZbQlJ9yO1hiaJ9_H67Y8dV3fQJs9X3_bFkT5QZuLCo,1887
+clinotes/server.py,sha256=CmCX7-BzcI3eo4gc8cM5DsjDdKCgZHNnisq-7M7Q2K8,3315
+clinotes/storage.py,sha256=Cug6X1X6v0ymPQJ7D-gnD2YZWC9CW1SKVd9w8aYDJ-4,4920
+clinotes-0.1.0.dist-info/METADATA,sha256=a5b2n77g9juvr1DgrvhxoklYYEjBU2HZfMxJ45xslOY,2807
+clinotes-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+clinotes-0.1.0.dist-info/entry_points.txt,sha256=ynv2iaU3ZkmkwKIdznu39DkbDTn9SzhwQD6O0sJ2irw,82
+clinotes-0.1.0.dist-info/licenses/LICENSE,sha256=gIqmRCCMX5ZKT4TJtX53YnZC4f1ah-AKidCqDrT23Rk,1093
+clinotes-0.1.0.dist-info/RECORD,,

clinotes-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

clinotes-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+clinotes = clinotes.cli:app
+clinotes-mcp = clinotes.server:main

clinotes-0.1.0.dist-info/licenses/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.