anamnestic 0.2.0__tar.gz

anamnestic-0.2.0/LICENSE

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

anamnestic-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: anamnestic
+Version: 0.2.0
+Summary: Persistent hybrid-search memory for AI CLI sessions (Claude Code, Codex, any turn-based jsonl)
+Author: xomyachok-shaolin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xomyachok-shaolin/anamnestic
+Project-URL: Repository, https://github.com/xomyachok-shaolin/anamnestic
+Project-URL: Issues, https://github.com/xomyachok-shaolin/anamnestic/issues
+Keywords: memory,search,mcp,claude,codex,rag,hybrid-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chromadb>=0.4
+Requires-Dist: fastembed>=0.6
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# anamnesis
+
+Персистентная память с гибридным поиском для сессий AI-CLI.
+
+Собирает исторические транскрипты из **Claude Code** (main + sub-агенты), **Codex CLI** и **VS Code Copilot** в единый корпус. Даёт гибридный поиск (BM25 + семантика + темпоральный + граф сущностей → RRF-слияние) и отдаёт результаты обратно клиентам как MCP-инструменты.
+
+Построено как слой-расширение поверх [`claude-mem`](https://github.com/thedotmack/claude-mem): переиспользует его SQLite-файл как базовую схему и добавляет собственные таблицы, индексы и сервисы. Оба сосуществуют, не конфликтуя.
+
+```
+pip install anamnestic
+```
+
+## Зачем
+
+- Транскрипты рабочих сессий с AI-агентами накапливаются между проектами и клиентами. Grep по jsonl — медленно и семантически слепо; сами клиенты всё забывают между запусками.
+- MCP-сервер, который на `mem_search("запрос")` возвращает ранжированные реплики из любой прошлой сессии, превращает архив в адресуемую поверхность знаний.
+- Только BM25 пропускает парафразы. Только семантика не видит точных токенов (IP, CVE, пути). Четырёхканальный RRF даёт каждому каналу шанс вытащить релевантное.
+
+## Архитектура
+
+```
+jsonl-источники (Claude Code / sub-агенты / Codex / VS Code Copilot)
+       │
+       │  mtime-сканер, парсер под формат
+       ▼
+SQLite ── historical_turns (+ FTS5)              ◄── BM25
+  │    ── session_summaries (+ FTS5)             ◄── BM25 (слой наблюдений)
+  │    ── anamnesis_entities                     ◄── поиск по сущностям
+  │    ── anamnesis_entity_edges                 ◄── обход графа
+  │
+  │  инкрементальный ONNX-эмбеддер (MiniLM-L12-v2)
+  ▼
+Chroma (persistent, file-based)                   ◄── семантика
+  │
+  │  4-канальный Reciprocal Rank Fusion (K=60)
+  │  + importance weighting + temporal decay
+  │  + cross-encoder reranking
+  ▼
+stdio MCP-сервер  ──►  Claude Code / Codex / любой MCP-клиент
+```
+
+## Поисковый пайплайн
+
+Четыре канала извлечения, объединённые через RRF:
+
+| Канал | Источник | Что находит |
+|-------|----------|-------------|
+| **BM25** | FTS5 по turns + саммари | Точные токены, пути к файлам, ошибки |
+| **Семантика** | Chroma cosine similarity | Парафразы, концептуально похожий контент |
+| **Темпоральный** | SQL по диапазону дат (EN/RU) | «вчера», «на прошлой неделе», «in March» |
+| **Граф** | BFS по co-occurrence сущностей | Связанные turns через общие пути/URL |
+
+Пост-фьюжн этапы:
+- **Importance weighting** — повышает turns с кодом, ошибками, решениями
+- **Temporal decay** — экспоненциальный полураспад (по умолчанию 90 дней), свежие результаты выше
+- **Cross-encoder reranking** — ONNX MiniLM перескорирует top-20 для финальной точности
+
+Каждый ответ поиска включает диагностику по каналам.
+
+## Контроль качества графа сущностей
+
+- **Минимальный вес ребра** — одноразовые co-occurrence (weight < 2) отсекаются как шум
+- **IDF-нормализация** — `score = weight / log₂(degree + 1)` подавляет сущности-хабы, поднимает редкие дискриминативные
+
+## MCP-инструменты
+
+| Инструмент | Назначение |
+|------------|------------|
+| `mem_search` | Гибридный поиск с выбором режима (hybrid/bm25/semantic) |
+| `mem_probe` | Оракул покрытия — «встречается ли этот токен?» |
+| `mem_entity` | Поиск по сущности — «что мы делали с этим файлом?» |
+| `mem_get_turn` | Получить turn с окружающим контекстом |
+| `mem_get_session` | Обзор сессии с метаданными |
+| `mem_get_thread` | Цепочка продолжений — все связанные сессии |
+| `mem_stats` | Статистика корпуса |
+| `mem_audit_tail` | Последние записи телеметрии |
+
+## CLI
+
+```bash
+anamnesis sync       # ingest + embed + обогащение (сущности, потоки, importance, саммари, граф)
+anamnesis search "запрос"
+anamnesis status     # снимок здоровья корпуса
+anamnesis verify     # проверки целостности (FTS, drift, сироты)
+anamnesis backup     # WAL-safe tar (хранит последние 10)
+anamnesis restore    # восстановление из бэкапа
+anamnesis audit      # лог последних операций
+anamnesis eval       # регрессионный тест по golden-запросам
+anamnesis archive    # архивация старых low-importance turns
+```
+
+## Установка
+
+Полная инструкция — установка, бэкфилл, регистрация MCP, systemd-таймеры, переезд — в **[SETUP.md](SETUP.md)**.
+
+## Принципы дизайна
+
+- **Файл — единица идемпотентности.** `anamnesis_ingest_state` хранит `(source, path, mtime_ns)`; повторный запуск пропускает неизменённые файлы.
+- **Turn — единица хранения.** `historical_turns` с UNIQUE-ключом `(content_session_id, turn_number)`; UPSERT не плодит дубликаты.
+- **Формат — ответственность парсера.** Добавить новый CLI-агент = написать парсер в `anamnesis/ingest/` и зарегистрировать glob.
+- **Каждая операция аудируется.** `anamnesis_audit` логирует sync/verify/backup/restore с длительностью и JSON-payload.
+- **Auto-sync при старте MCP.** Лёгкий ingest + embed при запуске сервера — данные всегда актуальны.
+
+## Тесты
+
+93 теста, покрывающие все модули:
+- Интеграционные тесты полного RRF-пайплайна (формула скора, multi-channel merge, importance, decay, граф, диагностика)
+- Unit-тесты importance scoring, temporal parsing, decay, entity extraction, graph traversal, reranking, threading, summarization, parsers, MCP server
+
+```bash
+pytest tests/ -v   # <1с
+```
+
+## Лицензия
+
+[MIT](LICENSE)

anamnestic-0.2.0/README.md

@@ -0,0 +1,116 @@
+# anamnesis
+
+Персистентная память с гибридным поиском для сессий AI-CLI.
+
+Собирает исторические транскрипты из **Claude Code** (main + sub-агенты), **Codex CLI** и **VS Code Copilot** в единый корпус. Даёт гибридный поиск (BM25 + семантика + темпоральный + граф сущностей → RRF-слияние) и отдаёт результаты обратно клиентам как MCP-инструменты.
+
+Построено как слой-расширение поверх [`claude-mem`](https://github.com/thedotmack/claude-mem): переиспользует его SQLite-файл как базовую схему и добавляет собственные таблицы, индексы и сервисы. Оба сосуществуют, не конфликтуя.
+
+```
+pip install anamnestic
+```
+
+## Зачем
+
+- Транскрипты рабочих сессий с AI-агентами накапливаются между проектами и клиентами. Grep по jsonl — медленно и семантически слепо; сами клиенты всё забывают между запусками.
+- MCP-сервер, который на `mem_search("запрос")` возвращает ранжированные реплики из любой прошлой сессии, превращает архив в адресуемую поверхность знаний.
+- Только BM25 пропускает парафразы. Только семантика не видит точных токенов (IP, CVE, пути). Четырёхканальный RRF даёт каждому каналу шанс вытащить релевантное.
+
+## Архитектура
+
+```
+jsonl-источники (Claude Code / sub-агенты / Codex / VS Code Copilot)
+       │
+       │  mtime-сканер, парсер под формат
+       ▼
+SQLite ── historical_turns (+ FTS5)              ◄── BM25
+  │    ── session_summaries (+ FTS5)             ◄── BM25 (слой наблюдений)
+  │    ── anamnesis_entities                     ◄── поиск по сущностям
+  │    ── anamnesis_entity_edges                 ◄── обход графа
+  │
+  │  инкрементальный ONNX-эмбеддер (MiniLM-L12-v2)
+  ▼
+Chroma (persistent, file-based)                   ◄── семантика
+  │
+  │  4-канальный Reciprocal Rank Fusion (K=60)
+  │  + importance weighting + temporal decay
+  │  + cross-encoder reranking
+  ▼
+stdio MCP-сервер  ──►  Claude Code / Codex / любой MCP-клиент
+```
+
+## Поисковый пайплайн
+
+Четыре канала извлечения, объединённые через RRF:
+
+| Канал | Источник | Что находит |
+|-------|----------|-------------|
+| **BM25** | FTS5 по turns + саммари | Точные токены, пути к файлам, ошибки |
+| **Семантика** | Chroma cosine similarity | Парафразы, концептуально похожий контент |
+| **Темпоральный** | SQL по диапазону дат (EN/RU) | «вчера», «на прошлой неделе», «in March» |
+| **Граф** | BFS по co-occurrence сущностей | Связанные turns через общие пути/URL |
+
+Пост-фьюжн этапы:
+- **Importance weighting** — повышает turns с кодом, ошибками, решениями
+- **Temporal decay** — экспоненциальный полураспад (по умолчанию 90 дней), свежие результаты выше
+- **Cross-encoder reranking** — ONNX MiniLM перескорирует top-20 для финальной точности
+
+Каждый ответ поиска включает диагностику по каналам.
+
+## Контроль качества графа сущностей
+
+- **Минимальный вес ребра** — одноразовые co-occurrence (weight < 2) отсекаются как шум
+- **IDF-нормализация** — `score = weight / log₂(degree + 1)` подавляет сущности-хабы, поднимает редкие дискриминативные
+
+## MCP-инструменты
+
+| Инструмент | Назначение |
+|------------|------------|
+| `mem_search` | Гибридный поиск с выбором режима (hybrid/bm25/semantic) |
+| `mem_probe` | Оракул покрытия — «встречается ли этот токен?» |
+| `mem_entity` | Поиск по сущности — «что мы делали с этим файлом?» |
+| `mem_get_turn` | Получить turn с окружающим контекстом |
+| `mem_get_session` | Обзор сессии с метаданными |
+| `mem_get_thread` | Цепочка продолжений — все связанные сессии |
+| `mem_stats` | Статистика корпуса |
+| `mem_audit_tail` | Последние записи телеметрии |
+
+## CLI
+
+```bash
+anamnesis sync       # ingest + embed + обогащение (сущности, потоки, importance, саммари, граф)
+anamnesis search "запрос"
+anamnesis status     # снимок здоровья корпуса
+anamnesis verify     # проверки целостности (FTS, drift, сироты)
+anamnesis backup     # WAL-safe tar (хранит последние 10)
+anamnesis restore    # восстановление из бэкапа
+anamnesis audit      # лог последних операций
+anamnesis eval       # регрессионный тест по golden-запросам
+anamnesis archive    # архивация старых low-importance turns
+```
+
+## Установка
+
+Полная инструкция — установка, бэкфилл, регистрация MCP, systemd-таймеры, переезд — в **[SETUP.md](SETUP.md)**.
+
+## Принципы дизайна
+
+- **Файл — единица идемпотентности.** `anamnesis_ingest_state` хранит `(source, path, mtime_ns)`; повторный запуск пропускает неизменённые файлы.
+- **Turn — единица хранения.** `historical_turns` с UNIQUE-ключом `(content_session_id, turn_number)`; UPSERT не плодит дубликаты.
+- **Формат — ответственность парсера.** Добавить новый CLI-агент = написать парсер в `anamnesis/ingest/` и зарегистрировать glob.
+- **Каждая операция аудируется.** `anamnesis_audit` логирует sync/verify/backup/restore с длительностью и JSON-payload.
+- **Auto-sync при старте MCP.** Лёгкий ingest + embed при запуске сервера — данные всегда актуальны.
+
+## Тесты
+
+93 теста, покрывающие все модули:
+- Интеграционные тесты полного RRF-пайплайна (формула скора, multi-channel merge, importance, decay, граф, диагностика)
+- Unit-тесты importance scoring, temporal parsing, decay, entity extraction, graph traversal, reranking, threading, summarization, parsers, MCP server
+
+```bash
+pytest tests/ -v   # <1с
+```
+
+## Лицензия
+
+[MIT](LICENSE)

anamnestic-0.2.0/anamnesis/__init__.py

@@ -0,0 +1,3 @@
+"""Anamnesis — persistent memory for AI CLI sessions."""
+
+__version__ = "0.2.0"

anamnestic-0.2.0/anamnesis/audit.py

@@ -0,0 +1,67 @@
+"""Audit log + health snapshot helpers."""
+import json
+import time
+from contextlib import contextmanager
+
+from anamnesis.config import HEALTH_FILE
+from anamnesis.db import connect
+
+
+def write_audit(action: str, status: str, duration_sec: float | None, details: dict):
+    conn = connect()
+    try:
+        conn.execute(
+            "INSERT INTO anamnesis_audit(action, status, duration_sec, details) "
+            "VALUES (?, ?, ?, ?)",
+            (action, status, duration_sec, json.dumps(details, ensure_ascii=False)),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def write_health(snapshot: dict):
+    snapshot = dict(snapshot)
+    snapshot.setdefault("written_at", time.strftime("%Y-%m-%dT%H:%M:%S"))
+    with open(HEALTH_FILE, "w") as f:
+        json.dump(snapshot, f, ensure_ascii=False, indent=2)
+
+
+@contextmanager
+def audited(action: str):
+    """Context manager: log start, duration, status=ok|error; re-raise."""
+    t0 = time.time()
+    details = {}
+    try:
+        yield details
+    except Exception as e:
+        dt = round(time.time() - t0, 2)
+        details["error"] = f"{type(e).__name__}: {e}"
+        write_audit(action, "error", dt, details)
+        raise
+    else:
+        dt = round(time.time() - t0, 2)
+        status = details.pop("_status", "ok")
+        write_audit(action, status, dt, details)
+
+
+def recent(limit: int = 20) -> list[dict]:
+    conn = connect()
+    try:
+        rows = conn.execute(
+            "SELECT at, action, status, duration_sec, details "
+            "FROM anamnesis_audit ORDER BY id DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+        return [
+            {
+                "at": r["at"],
+                "action": r["action"],
+                "status": r["status"],
+                "duration_sec": r["duration_sec"],
+                "details": json.loads(r["details"]) if r["details"] else {},
+            }
+            for r in rows
+        ]
+    finally:
+        conn.close()

anamnestic-0.2.0/anamnesis/backup.py

@@ -0,0 +1,61 @@
+"""Safe backup of SQLite + Chroma to a dated tarball.
+
+Uses SQLite .backup API (WAL-safe, online copy). Tars Chroma directory.
+Output: ~/claude-mem-backups/claude-mem-YYYYMMDD-HHMMSS.tar.gz
+"""
+import os
+import shutil
+import sqlite3
+import tarfile
+import time
+from pathlib import Path
+
+from anamnesis.config import DB_PATH, CHROMA_DIR, BACKUP_ROOT, BACKUP_KEEP_LAST
+
+KEEP_LAST = BACKUP_KEEP_LAST
+
+
+def _safe_sqlite_copy(dst):
+    """Online, consistent copy of WAL-mode SQLite."""
+    src = sqlite3.connect(f"file:{DB_PATH}?mode=ro", uri=True)
+    dst_conn = sqlite3.connect(dst)
+    with dst_conn:
+        src.backup(dst_conn)
+    dst_conn.close()
+    src.close()
+
+
+def run():
+    os.makedirs(BACKUP_ROOT, exist_ok=True)
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    work = Path(BACKUP_ROOT) / f"work-{stamp}"
+    work.mkdir(parents=True, exist_ok=True)
+
+    db_copy = work / "claude-mem.db"
+    chroma_copy = work / "semantic-chroma"
+
+    _safe_sqlite_copy(str(db_copy))
+    if os.path.isdir(CHROMA_DIR):
+        shutil.copytree(CHROMA_DIR, chroma_copy)
+    else:
+        chroma_copy.mkdir(parents=True, exist_ok=True)
+
+    archive = Path(BACKUP_ROOT) / f"claude-mem-{stamp}.tar.gz"
+    with tarfile.open(archive, "w:gz") as tf:
+        tf.add(db_copy, arcname="claude-mem.db")
+        tf.add(chroma_copy, arcname="semantic-chroma")
+    shutil.rmtree(work)
+
+    # retention
+    archives = sorted(Path(BACKUP_ROOT).glob("claude-mem-*.tar.gz"))
+    if len(archives) > KEEP_LAST:
+        for old in archives[:-KEEP_LAST]:
+            old.unlink()
+
+    size_mb = archive.stat().st_size / (1024 * 1024)
+    return {"path": str(archive), "size_mb": round(size_mb, 1)}
+
+
+if __name__ == "__main__":
+    info = run()
+    print(f"Backup: {info['path']} ({info['size_mb']} MB)")