claude-memory-engine 0.6.0__py3-none-any.whl

claude_memory/__init__.py

@@ -0,0 +1,16 @@
+"""claude-memory-engine — переиспользуемый движок «памяти уроков» для Claude Code.
+
+Универсальная (не привязанная к конкретному проекту) часть системы памяти: файловое
+хранилище уроков с frontmatter, авто-указатель CATALOG, офлайн-ретривер, всплытие
+уроков по пути файла, авто-обслуживание, страж параллельных правок и страж выбора
+модели суб-агентов. Все проектные значения — в claude_memory.config.MemoryConfig.
+
+Происхождение: извлечено из инструментария реального рабочего проекта.
+"""
+from __future__ import annotations
+
+__version__ = "0.6.0"
+
+from .config import MemoryConfig, get_config, load
+
+__all__ = ["MemoryConfig", "get_config", "load", "__version__"]

claude_memory/applies_to.py

@@ -0,0 +1,152 @@
+"""Поиск «путь → уроки»: по пути файла находит уроки, чьи `applies_to:`-глобы
+(frontmatter) совпадают с этим путём.
+
+Раньше эта логика жила Python-вставкой внутри bash-хука `lessons_for_path.sh` и
+дублировалась вызовом из ретривера. Здесь она — один Python-модуль, который зовут И
+ретривер (`memory_retrieve.path_lessons`), И тонкая обёртка-хук «перед первой правкой
+файла». Один источник истины, без shell-зависимости, тестируемо.
+
+`applies_to` задаётся относительно корня проекта; матчинг идёт по пути,
+релативизированному к корню проекта (а если не вышло — к git-toplevel; работает и в
+worktree).
+"""
+from __future__ import annotations
+
+import fnmatch
+import glob
+import os
+import re
+import subprocess
+from typing import List, Optional, Tuple
+
+from .config import MemoryConfig, get_config
+
+_APPLIES_RE = re.compile(r"^[ \t]*applies_to:[ \t]*(.*)$", re.MULTILINE)
+_DESC_RE = re.compile(r"^description:\s*(.*)$", re.MULTILINE)
+
+
+def read_head(path: str, cap: int = 65536) -> str:
+    """Начало файла до cap байт (по умолч. 64К). Покрывает весь frontmatter любого
+    реального урока + начало тела. Заменяет прежние фикс.окна 2000/4000, которые молча
+    ТЕРЯЛИ длинный frontmatter (и applies_to-глоб, и поля для ретривера). Уроки малы —
+    цена чтения ничтожна. OSError пробрасывается вызывающему."""
+    with open(path, encoding="utf-8") as f:
+        return f.read(cap)
+
+
+def _frontmatter(path: str) -> str:
+    try:
+        head = read_head(path)
+    except OSError:
+        return ""
+    if not head.startswith("---"):
+        return ""
+    return head.split("\n---", 1)[0]
+
+
+def _applies_globs(fm: str) -> List[str]:
+    """Глобы из `applies_to:` — инлайн-список `[a, b]` ИЛИ YAML-список из `- `-строк.
+
+    Ведущий [ \\t]* ловит И top-level applies_to, И вложенный под `metadata:` (нативный
+    формат памяти harness). После `:` — [ \\t]* (не \\s*), иначе потеряется 1-й элемент
+    многострочного списка.
+    """
+    m = _APPLIES_RE.search(fm)
+    if not m:
+        return []
+    inline = m.group(1).strip()
+    if inline.startswith("["):
+        inner = inline.strip("[]")
+        return [g.strip().strip("'\"") for g in inner.split(",") if g.strip()]
+    globs: List[str] = []
+    for line in fm[m.end():].splitlines():
+        ls = line.strip()
+        if ls.startswith("- "):
+            globs.append(ls[2:].strip().strip("'\""))
+        elif ls and not ls.startswith("#"):
+            break
+    return [g for g in globs if g]
+
+
+def _candidates(target: str, project_root: str) -> set:
+    """Пути-кандидаты для матчинга глоб: исходный аргумент + rel-к-корню-проекта +
+    rel-к-git-toplevel.
+
+    Оба rel считаем ВСЕГДА и добавляем оба (а не «или»): в worktree-сессии путь лежит
+    под главным project_root (rel получится `.claude/worktrees/<wt>/app/x.py` — НЕ
+    матчит глоб `app/*`), но git-toplevel = корень worktree → rel `app/x.py` матчит.
+    Так applies_to работает одинаково и в worktree, и вне его (#memory-lib-cutover).
+    """
+    abspath = os.path.abspath(target)
+    # removeprefix («./»), НЕ lstrip(«./»): lstrip снимает КЛАСС символов {'.', '/'} и
+    # портит dotfile-пути ('.github/x.yml' → 'github/x.yml'), порождая ложный кандидат,
+    # способный совпасть с typo-глобом. Нужно снять ровно ведущий «./» относительного пути.
+    cands = {target, target.removeprefix("./")}
+    # 1) относительно корня проекта из конфига
+    try:
+        root_abs = os.path.abspath(project_root)
+        if root_abs and abspath.startswith(root_abs + os.sep):
+            cands.add(os.path.relpath(abspath, root_abs))
+    except (OSError, ValueError):
+        pass
+    # 2) относительно git-toplevel (в worktree это корень worktree → совпадает с глобами)
+    search_dir = abspath if os.path.isdir(abspath) else os.path.dirname(abspath)
+    try:
+        top = subprocess.check_output(
+            ["git", "-C", search_dir, "rev-parse", "--show-toplevel"],
+            stderr=subprocess.DEVNULL, text=True,
+        ).strip()
+        if top and abspath.startswith(top + os.sep):
+            cands.add(os.path.relpath(abspath, top))
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return {c for c in cands if c}
+
+
+def find_lessons_for_path(
+    target: str, cfg: Optional[MemoryConfig] = None
+) -> List[Tuple[str, str]]:
+    """Список (имя_файла_урока, описание) уроков, чьи applies_to-глобы матчат target.
+
+    Отсортировано по имени файла. Описание — из `description:` frontmatter ("" если нет).
+    """
+    cfg = cfg or get_config()
+    if not target:
+        return []
+    candidates = _candidates(target, cfg.project_root)
+    out: List[Tuple[str, str]] = []
+    for mf in sorted(glob.glob(os.path.join(cfg.memory_dir, "*.md"))):
+        fm = _frontmatter(mf)
+        if not fm:
+            continue
+        globs = _applies_globs(fm)
+        if not globs:
+            continue
+        if not any(
+            cand == g or fnmatch.fnmatch(cand, g) for g in globs for cand in candidates
+        ):
+            continue
+        dm = _DESC_RE.search(fm)
+        desc = dm.group(1).strip() if dm else ""
+        out.append((os.path.basename(mf), desc))
+    return out
+
+
+def format_lines(matches: List[Tuple[str, str]]) -> str:
+    """Формат вывода хука/CLI: одна строка `- имя: описание` на урок."""
+    return "\n".join(f"- {n}: {d}" if d else f"- {n}" for n, d in matches)
+
+
+def main() -> None:
+    import sys
+
+    target = sys.argv[1] if len(sys.argv) > 1 else ""
+    if not target:
+        return
+    matches = find_lessons_for_path(target)
+    if matches:
+        print(format_lines(matches))
+
+
+if __name__ == "__main__":
+    main()

claude_memory/archive_prune.py

@@ -0,0 +1,74 @@
+"""CLI: безопасное удаление архивных уроков с истёкшим сроком хранения.
+
+Кандидаты = `staleness.scan_archive_stale` (архивные уроки с `archived_on` старше
+`archive_stale_months`). Без `--apply` — только печать (dry-run). С `--apply` — каждый
+файл СНАЧАЛА копируется в бэкап `<memory_dir>/_deleted/<сегодня>/` (вне всех глобов
+движка → не всплывёт снова), ПОТОМ удаляется оригинал. Память не под git → удаление
+необратимо, бэкап — единственная подстраховка; чистить `_deleted/` пользователь может сам.
+
+Память сама себя не удаляет: эту команду запускает человек осознанно (а напоминание о
+кандидатах приходит из `_stale_pending` на старте сессии). 0 токенов ИИ — чистый скрипт.
+"""
+from __future__ import annotations
+
+import datetime
+import shutil
+import sys
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from .config import MemoryConfig, get_config
+from .messages import msg
+from . import staleness
+
+# Бэкап удалённого — в `_`-каталоге верхнего уровня memory_dir: вне archive/** (скан
+# хранения), вне `*.md` верхнего уровня (каталог/ретрив/applies_to) → не переоткроется.
+BACKUP_DIR = "_deleted"
+
+
+def prune(
+    cfg: Optional[MemoryConfig] = None,
+    apply: bool = False,
+    today: Optional[datetime.date] = None,
+) -> Tuple[List[Tuple[str, str, int, str]], List[str]]:
+    """(кандидаты, удалённые). Без apply — удалённые пусты. С apply — бэкап ДО удаления."""
+    cfg = cfg or get_config()
+    today = today or datetime.date.today()
+    cands = staleness.scan_archive_stale(cfg, today)
+    if not apply or not cands:
+        return cands, []
+    arc_root = Path(cfg.memory_dir) / cfg.archive_dir_name
+    backup_root = Path(cfg.memory_dir) / BACKUP_DIR / today.isoformat()
+    deleted: List[str] = []
+    for _d, name, _months, _desc in cands:
+        matches = list(arc_root.rglob(name))
+        if not matches:
+            continue
+        src = matches[0]
+        backup_root.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, backup_root / name)
+        src.unlink()
+        deleted.append(name)
+    return cands, deleted
+
+
+def main() -> None:
+    cfg = get_config()
+    apply = "--apply" in sys.argv[1:]
+    cands, deleted = prune(cfg, apply=apply)
+    if not cands:
+        print(msg(cfg, "archive_prune.none"))
+        return
+    if not apply:
+        print(msg(cfg, "archive_prune.list_header", count=len(cands)))
+        for d, name, months, _desc in cands:
+            print(msg(cfg, "archive_prune.list_item", name=name, d=d, months=months))
+        print(msg(cfg, "archive_prune.apply_hint"))
+    else:
+        print(msg(cfg, "archive_prune.deleted", count=len(deleted), backup_dir=BACKUP_DIR))
+        for name in deleted:
+            print(msg(cfg, "archive_prune.deleted_item", name=name))
+
+
+if __name__ == "__main__":
+    main()