cairn-mem 0.1.0__tar.gz

cairn_mem-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DavidPerezOrfila
+
+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.

cairn_mem-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: cairn-mem
+Version: 0.1.0
+Summary: Memoria persistente para agentes de código: CLI + archivos, sin LLM
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/DavidPerezOrfila/cairn-mem
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# cairn-mem
+
+Memoria persistente para agentes de código: **CLI + archivos**, sin LLM y sin dependencias.
+Funciona con cualquier agente/arnés que tenga shell.
+
+Una memoria es una decisión, convención, gotcha o hecho del proyecto, con su motivo.
+Cairn la guarda en `.cairn/events.jsonl` (append-only, es la verdad) y mantiene un
+índice FTS5 y un L0 compacto (`.cairn/MEMORY.md`) que el agente puede leer al arrancar.
+
+## Instalación
+
+```bash
+pipx install cairn-mem      # comando global `cairn`
+# o, para desarrollar:
+pip install -e ".[dev]"
+```
+
+## Uso
+
+```bash
+cairn init [--share]        # crea .cairn/ (local-only por defecto)
+cairn save --kind gotcha --topic auth/redirect --title "..." --body "..." --why "..." --anchor src/auth.py
+cairn search "oauth callback" --limit 5     # L1: id, kind, title, snippet, stale
+cairn get <id>                              # L2: memoria completa
+cairn render                                # L0: regenera e imprime MEMORY.md (≤ 3000 car.)
+cairn check                                 # memorias con ancla cambiada (⚠ revisar)
+cairn archive <id>                          # deja de aparecer
+cairn rebuild                               # reconstruye cairn.db desde events.jsonl
+```
+
+- `kind`: `decision | convention | gotcha | fact`. `body` ≤ 500 caracteres.
+- Mismo `--topic` reemplaza la memoria anterior; no dupliques.
+- `--json` en `save`, `search`, `get` y `check` para consumo desde agentes.
+- Secretos: se **rechazan** antes de escribir (claves cloud, JWT, `password = ...`, URLs con credenciales).
+
+## Integración con un agente
+
+Copia el snippet de [`docs/AGENT_SNIPPET.md`](docs/AGENT_SNIPPET.md) en el `AGENTS.md`/`CLAUDE.md`
+del proyecto. Verificado guardando en un arnés y recuperando en otro (OpenCode y GitHub Copilot CLI).
+
+## Diseño
+
+- Verdad: `.cairn/events.jsonl` (2 operaciones: `save`, `archive`).
+- Derivados y regenerables: `cairn.db` (SQLite + FTS5) y `MEMORY.md`.
+- Búsqueda BM25 con consultas saneadas (AND y fallback OR), sin embeddings.
+- `stale` se calcula al leer comparando el hash del ancla (CRLF→LF), no se persiste.
+- Detalle: [`docs/DESIGN.md`](docs/DESIGN.md) · Decisiones: [`docs/DECISIONS.md`](docs/DECISIONS.md) · Medidas: [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md).
+
+## Estado
+
+v0.1.0. Hitos: [`PLAN.md`](PLAN.md). Reglas de desarrollo: [`AGENTS.md`](AGENTS.md).
+
+## Desarrollo
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+ruff check src tests bench
+python bench/bench_cli.py --reps 20
+```
+
+Python 3.10+; el núcleo usa solo la stdlib.

cairn_mem-0.1.0/README.md

@@ -0,0 +1,62 @@
+# cairn-mem
+
+Memoria persistente para agentes de código: **CLI + archivos**, sin LLM y sin dependencias.
+Funciona con cualquier agente/arnés que tenga shell.
+
+Una memoria es una decisión, convención, gotcha o hecho del proyecto, con su motivo.
+Cairn la guarda en `.cairn/events.jsonl` (append-only, es la verdad) y mantiene un
+índice FTS5 y un L0 compacto (`.cairn/MEMORY.md`) que el agente puede leer al arrancar.
+
+## Instalación
+
+```bash
+pipx install cairn-mem      # comando global `cairn`
+# o, para desarrollar:
+pip install -e ".[dev]"
+```
+
+## Uso
+
+```bash
+cairn init [--share]        # crea .cairn/ (local-only por defecto)
+cairn save --kind gotcha --topic auth/redirect --title "..." --body "..." --why "..." --anchor src/auth.py
+cairn search "oauth callback" --limit 5     # L1: id, kind, title, snippet, stale
+cairn get <id>                              # L2: memoria completa
+cairn render                                # L0: regenera e imprime MEMORY.md (≤ 3000 car.)
+cairn check                                 # memorias con ancla cambiada (⚠ revisar)
+cairn archive <id>                          # deja de aparecer
+cairn rebuild                               # reconstruye cairn.db desde events.jsonl
+```
+
+- `kind`: `decision | convention | gotcha | fact`. `body` ≤ 500 caracteres.
+- Mismo `--topic` reemplaza la memoria anterior; no dupliques.
+- `--json` en `save`, `search`, `get` y `check` para consumo desde agentes.
+- Secretos: se **rechazan** antes de escribir (claves cloud, JWT, `password = ...`, URLs con credenciales).
+
+## Integración con un agente
+
+Copia el snippet de [`docs/AGENT_SNIPPET.md`](docs/AGENT_SNIPPET.md) en el `AGENTS.md`/`CLAUDE.md`
+del proyecto. Verificado guardando en un arnés y recuperando en otro (OpenCode y GitHub Copilot CLI).
+
+## Diseño
+
+- Verdad: `.cairn/events.jsonl` (2 operaciones: `save`, `archive`).
+- Derivados y regenerables: `cairn.db` (SQLite + FTS5) y `MEMORY.md`.
+- Búsqueda BM25 con consultas saneadas (AND y fallback OR), sin embeddings.
+- `stale` se calcula al leer comparando el hash del ancla (CRLF→LF), no se persiste.
+- Detalle: [`docs/DESIGN.md`](docs/DESIGN.md) · Decisiones: [`docs/DECISIONS.md`](docs/DECISIONS.md) · Medidas: [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md).
+
+## Estado
+
+v0.1.0. Hitos: [`PLAN.md`](PLAN.md). Reglas de desarrollo: [`AGENTS.md`](AGENTS.md).
+
+## Desarrollo
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+ruff check src tests bench
+python bench/bench_cli.py --reps 20
+```
+
+Python 3.10+; el núcleo usa solo la stdlib.

cairn_mem-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cairn-mem"
+version = "0.1.0"
+description = "Memoria persistente para agentes de código: CLI + archivos, sin LLM"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/DavidPerezOrfila/cairn-mem"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff"]
+
+[project.scripts]
+cairn = "cairn_mem.cli:main"
+cairn-mem = "cairn_mem.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cairn_mem-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cairn_mem-0.1.0/src/cairn_mem/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cairn_mem-0.1.0/src/cairn_mem/anchor.py

@@ -0,0 +1,20 @@
+"""Anclas de fichero: hash estable entre SO y stale calculado al leer."""
+
+import hashlib
+from pathlib import Path
+
+
+def file_hash(path) -> str:
+    data = Path(path).read_bytes().replace(b"\r\n", b"\n")
+    return hashlib.sha1(data).hexdigest()
+
+
+def is_stale(anchor_path, anchor_hash, project_root) -> bool:
+    if not anchor_path or not anchor_hash:
+        return False
+    try:
+        return file_hash(Path(project_root) / anchor_path) != anchor_hash
+    except OSError:
+        # No se pudo leer (falta, es carpeta o está bloqueado): no se puede
+        # confirmar el hash, así que se avisa. Nunca se oculta la memoria.
+        return True

cairn_mem-0.1.0/src/cairn_mem/cli.py

@@ -0,0 +1,221 @@
+"""CLI de cairn-mem (M1)."""
+
+import argparse
+import json
+import os
+import sqlite3
+import sys
+from pathlib import Path
+
+from cairn_mem.anchor import file_hash, is_stale
+from cairn_mem.store import KINDS, Store
+
+GITIGNORE = ("cairn.db", "cairn.db-*", "MEMORY.md")
+
+
+def _data_dir() -> Path:
+    env = os.environ.get("CAIRN_DIR")
+    if env:
+        return Path(env)
+    cwd = Path.cwd().resolve()
+    for folder in (cwd, *cwd.parents):
+        if (folder / ".cairn").is_dir():
+            return folder / ".cairn"
+    raise FileNotFoundError(
+        "no se encontró .cairn/ en este árbol; ejecuta 'cairn init'"
+    )
+
+
+def _print_json(value) -> None:
+    print(json.dumps(value, ensure_ascii=False))
+
+
+def _anchor(path: str, project_root: Path) -> tuple[str, str]:
+    file = Path(path)
+    if not file.is_absolute():
+        file = project_root / file
+    if not file.is_file():
+        raise FileNotFoundError(f"ancla no encontrada: {path}")
+    try:
+        relative = Path(
+            os.path.relpath(file.resolve(), project_root.resolve())
+        ).as_posix()
+    except ValueError as error:
+        raise ValueError(f"el ancla debe estar dentro del proyecto: {path}") from error
+    return relative, file_hash(file)
+
+
+def _cmd_init(ns) -> int:
+    env = os.environ.get("CAIRN_DIR")
+    root = Path(env) if env else Path.cwd() / ".cairn"
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "events.jsonl").touch()
+    lines = list(GITIGNORE)
+    if not ns.share:
+        lines.append("events.jsonl")
+    (root / ".gitignore").write_text("\n".join(lines) + "\n", encoding="utf-8")
+    Store(str(root))
+    print(f"cairn inicializado en {root}")
+    return 0
+
+
+def _cmd_save(ns) -> int:
+    anchor_path = anchor_hash = None
+    if ns.anchor:
+        anchor_path, anchor_hash = _anchor(ns.anchor, _data_dir().parent)
+    mid = Store(str(_data_dir())).save(
+        kind=ns.kind,
+        title=ns.title,
+        body=ns.body,
+        why=ns.why,
+        topic_key=ns.topic,
+        anchor_path=anchor_path,
+        anchor_hash=anchor_hash,
+        id=ns.id,
+    )
+    _print_json({"id": mid}) if ns.json else print(mid)
+    return 0
+
+
+def _cmd_search(ns) -> int:
+    results = Store(str(_data_dir())).search(ns.query, limit=ns.limit)
+    if ns.json:
+        _print_json(results)
+    elif not results:
+        print("sin resultados")
+    else:
+        for r in results:
+            snippet = " ".join(r["snippet"].split())
+            stale = "  ⚠ revisar" if r["stale"] else ""
+            print(f"{r['id']}  {r['kind']}  {r['title']} — {snippet}{stale}")
+    return 0
+
+
+def _cmd_get(ns) -> int:
+    memory = Store(str(_data_dir())).get(ns.id)
+    if memory is None:
+        raise ValueError(f"no existe la memoria {ns.id}")
+    if ns.json:
+        _print_json(memory)
+    else:
+        for key, value in memory.items():
+            if value is not None:
+                print(f"{key}: {value}")
+    return 0
+
+
+def _cmd_archive(ns) -> int:
+    store = Store(str(_data_dir()))
+    if store.get(ns.id) is None:
+        raise ValueError(f"no existe la memoria {ns.id}")
+    store.archive(ns.id)
+    print(f"archivada {ns.id}")
+    return 0
+
+
+def _cmd_rebuild(ns) -> int:
+    store = Store(str(_data_dir()))
+    store.rebuild()
+    print(f"reconstruida: {len(store.dump())} memorias")
+    return 0
+
+
+def _cmd_render(ns) -> int:
+    print(Store(str(_data_dir())).write_l0(), end="")
+    return 0
+
+
+def _cmd_check(ns) -> int:
+    data_dir = _data_dir()
+    root = data_dir.parent
+    stale = [
+        row
+        for row in Store(str(data_dir)).dump()
+        if row["status"] == "active"
+        and is_stale(row["anchor_path"], row["anchor_hash"], root)
+    ]
+    if ns.json:
+        _print_json(
+            [
+                {
+                    "id": row["id"],
+                    "kind": row["kind"],
+                    "title": row["title"],
+                    "anchor_path": row["anchor_path"],
+                }
+                for row in stale
+            ]
+        )
+    elif not stale:
+        print("sin memorias stale")
+    else:
+        for row in stale:
+            print(f"{row['id']}  {row['kind']}  {row['title']}  ({row['anchor_path']})")
+    return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="cairn", description="Memoria persistente para agentes"
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init", help="crea .cairn/ (local-only por defecto)")
+    init.add_argument("--share", action="store_true", help="versiona events.jsonl")
+    init.set_defaults(handler=_cmd_init)
+
+    save = sub.add_parser("save", help="guarda una memoria")
+    save.add_argument("--kind", required=True, choices=KINDS)
+    save.add_argument("--title", required=True)
+    save.add_argument("--body", required=True)
+    save.add_argument("--why")
+    save.add_argument("--topic", dest="topic")
+    save.add_argument("--anchor")
+    save.add_argument("--id")
+    save.add_argument("--json", action="store_true")
+    save.set_defaults(handler=_cmd_save)
+
+    search = sub.add_parser("search", help="busca memorias activas")
+    search.add_argument("query")
+    search.add_argument("--limit", type=int, default=5)
+    search.add_argument("--json", action="store_true")
+    search.set_defaults(handler=_cmd_search)
+
+    get = sub.add_parser("get", help="muestra una memoria completa")
+    get.add_argument("id")
+    get.add_argument("--json", action="store_true")
+    get.set_defaults(handler=_cmd_get)
+
+    archive = sub.add_parser("archive", help="archiva una memoria")
+    archive.add_argument("id")
+    archive.set_defaults(handler=_cmd_archive)
+
+    rebuild = sub.add_parser("rebuild", help="reconstruye la DB desde events.jsonl")
+    rebuild.set_defaults(handler=_cmd_rebuild)
+
+    render = sub.add_parser("render", help="regenera y muestra MEMORY.md (L0)")
+    render.set_defaults(handler=_cmd_render)
+
+    check = sub.add_parser("check", help="lista memorias con ancla stale")
+    check.add_argument("--json", action="store_true")
+    check.set_defaults(handler=_cmd_check)
+    return p
+
+
+def main(argv=None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    ns = _parser().parse_args(argv)
+    try:
+        return ns.handler(ns)
+    except (ValueError, FileNotFoundError) as error:
+        print(f"cairn: {error}", file=sys.stderr)
+        return 1
+    except sqlite3.Error:
+        print("cairn: error de base de datos; ejecuta 'cairn rebuild'", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cairn_mem-0.1.0/src/cairn_mem/render.py

@@ -0,0 +1,37 @@
+"""L0: MEMORY.md determinista con presupuesto de caracteres."""
+
+from pathlib import Path
+
+from cairn_mem.anchor import is_stale
+
+KIND_PRIORITY = {"convention": 0, "decision": 1, "gotcha": 2, "fact": 3}
+EXCERPT = 120
+TITLE = "# Memoria del proyecto (cairn L0)"
+
+
+def render_l0(store, max_chars: int = 3000, project_root=None) -> str:
+    """Orden fijo por kind y ts desc, cortado al presupuesto."""
+    root = Path(project_root) if project_root else Path(store.root).parent
+    rows = [row for row in store.dump() if row["status"] == "active"]
+    rows.sort(
+        key=lambda row: (
+            KIND_PRIORITY.get(row["kind"], len(KIND_PRIORITY)),
+            -row["ts"],
+            row["id"],
+        )
+    )
+    lines = [TITLE]
+    for row in rows:
+        line = _line(row, root)
+        if len("\n".join([*lines, line])) + 1 > max_chars:
+            break
+        lines.append(line)
+    return "\n".join(lines) + "\n"
+
+
+def _line(row: dict, root: Path) -> str:
+    body = " ".join(row["body"].split())[:EXCERPT]
+    text = f"- [{row['id']}] {row['kind']}: {row['title']} — {body}"
+    if is_stale(row["anchor_path"], row["anchor_hash"], root):
+        text += " ⚠ revisar"
+    return text