memory-lab-mcp 0.1.1__py3-none-any.whl

claude_memory_lab/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.1"

claude_memory_lab/auto_memory_import.py

@@ -0,0 +1,427 @@
+from __future__ import annotations
+
+import ast
+import hashlib
+import json
+import os
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+
+from claude_memory_lab.memory import (
+    add_memory,
+    classify_risk,
+    get_memory,
+    normalize_project_key,
+    supersede_memory,
+    update_memory,
+)
+
+SOURCE_METADATA_KEYS = (
+    "source_kind",
+    "source_path",
+    "source_type",
+    "source_name",
+    "origin_session_id",
+    "content_sha256",
+)
+
+TYPE_MAPPING = {
+    "feedback": "preference",
+    "project": "knowledge",
+    "reference": "knowledge",
+    "user": "preference",
+}
+
+
+@dataclass(frozen=True)
+class AutoMemory:
+    path: Path
+    name: str
+    content: str
+    source_type: str
+    memory_type: str
+    origin_session_id: str | None
+    content_sha256: str
+
+
+@dataclass(frozen=True)
+class ImportAction:
+    kind: str
+    memory: AutoMemory
+    memory_id: int | None = None
+    duplicate_id: int | None = None
+
+
+def _parse_scalar(value: str, path: Path, key: str) -> str:
+    value = value.strip()
+    if not value or value in {">", "|", ">-", "|-"}:
+        raise ValueError(f"unsupported {key} in {path}")
+    if value[0] in {'"', "'"}:
+        try:
+            parsed = ast.literal_eval(value)
+        except (SyntaxError, ValueError) as exc:
+            raise ValueError(f"invalid quoted {key} in {path}") from exc
+        if not isinstance(parsed, str):
+            raise ValueError(f"invalid {key} in {path}")
+        return parsed.strip()
+    return value
+
+
+def parse_auto_memory(path: Path) -> AutoMemory:
+    text = path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise ValueError(f"missing frontmatter in {path}")
+    try:
+        closing = next(index for index, line in enumerate(lines[1:], start=1) if line.strip() == "---")
+    except StopIteration as exc:
+        raise ValueError(f"unterminated frontmatter in {path}") from exc
+
+    fields: dict[str, str] = {}
+    metadata: dict[str, str] = {}
+    section: str | None = None
+    for line in lines[1:closing]:
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        indentation = len(line) - len(line.lstrip())
+        if ":" not in line:
+            raise ValueError(f"malformed frontmatter in {path}")
+        key, value = line.strip().split(":", 1)
+        if indentation == 0:
+            section = key if not value.strip() else None
+            if value.strip():
+                fields[key] = _parse_scalar(value, path, key)
+        elif section == "metadata":
+            metadata[key] = _parse_scalar(value, path, f"metadata.{key}")
+        else:
+            raise ValueError(f"unsupported nested frontmatter in {path}")
+
+    name = fields.get("name", "").strip()
+    content = fields.get("description", "").strip()
+    source_type = (fields.get("type") or metadata.get("type") or "").strip().lower()
+    if not name:
+        raise ValueError(f"missing name in {path}")
+    if not content:
+        raise ValueError(f"missing description in {path}")
+    if source_type not in TYPE_MAPPING:
+        raise ValueError(f"unknown auto-memory type {source_type!r} in {path}")
+
+    return AutoMemory(
+        path=path,
+        name=name,
+        content=content,
+        source_type=source_type,
+        memory_type=TYPE_MAPPING[source_type],
+        origin_session_id=fields.get("originSessionId") or metadata.get("originSessionId"),
+        content_sha256=hashlib.sha256(content.encode("utf-8")).hexdigest(),
+    )
+
+
+def load_selected_memories(source_dir: Path, includes: list[str]) -> list[AutoMemory]:
+    root = source_dir.expanduser().resolve()
+    if not root.is_dir():
+        raise ValueError(f"auto-memory directory not found: {root}")
+
+    memories = []
+    seen_paths = set()
+    for include in includes:
+        path = (root / include).resolve()
+        if path.parent != root:
+            raise ValueError(f"auto-memory path must be directly inside {root}: {include}")
+        if path.name == "MEMORY.md" or path in seen_paths:
+            continue
+        seen_paths.add(path)
+        if path.suffix.lower() != ".md" or not path.is_file():
+            raise ValueError(f"auto-memory file not found: {path}")
+        memories.append(parse_auto_memory(path))
+    return memories
+
+
+def _metadata(memory: AutoMemory) -> dict[str, object]:
+    metadata: dict[str, object] = {
+        "source_kind": "claude_auto_memory",
+        "source_path": str(memory.path),
+        "source_type": memory.source_type,
+        "source_name": memory.name,
+        "content_sha256": memory.content_sha256,
+    }
+    if memory.origin_session_id:
+        metadata["origin_session_id"] = memory.origin_session_id
+    return metadata
+
+
+def _source_metadata_view(metadata: dict[str, object]) -> dict[str, object]:
+    return {key: metadata.get(key) for key in SOURCE_METADATA_KEYS}
+
+
+def plan_auto_memory_import(
+    conn: sqlite3.Connection | None,
+    source_dir: Path,
+    includes: list[str],
+    project: str,
+) -> list[ImportAction]:
+    memories = load_selected_memories(source_dir, includes)
+    project_key = normalize_project_key(project)
+    if project_key is None:
+        raise ValueError("project must not be blank")
+    rows = (
+        conn.execute(
+            """
+            select id, content, memory_type, status, risk_tier, metadata_json
+            from memories
+            where status in ('active', 'pending')
+            and (lower(project_key) = ? or project_key is null)
+            order by case status when 'active' then 0 else 1 end, id
+            """,
+            (project_key,),
+        ).fetchall()
+        if conn is not None
+        else []
+    )
+    by_source: dict[str, sqlite3.Row] = {}
+    by_hash: dict[str, list[sqlite3.Row]] = {}
+    row_hashes: dict[int, str] = {}
+    for row in rows:
+        metadata = json.loads(row["metadata_json"])
+        content_hash = metadata.get("content_sha256")
+        if not isinstance(content_hash, str):
+            content_hash = hashlib.sha256(
+                row["content"].strip().encode("utf-8")
+            ).hexdigest()
+        row_hashes[int(row["id"])] = content_hash
+        by_hash.setdefault(content_hash, []).append(row)
+        if metadata.get("source_kind") == "claude_auto_memory":
+            source_path = metadata.get("source_path")
+            if isinstance(source_path, str):
+                by_source[source_path] = row
+
+    vacated_ids = {
+        int(source_row["id"])
+        for memory in memories
+        if (source_row := by_source.get(str(memory.path))) is not None
+        and row_hashes[int(source_row["id"])] != memory.content_sha256
+    }
+
+    def available_duplicate(content_hash: str) -> sqlite3.Row | None:
+        return next(
+            (
+                row
+                for row in by_hash.get(content_hash, [])
+                if int(row["id"]) not in vacated_ids
+            ),
+            None,
+        )
+
+    if os.getenv("MEMORY_LAB_REQUIRE_REVIEW", "") == "1":
+        pending_changes = []
+        for memory in memories:
+            source_row = by_source.get(str(memory.path))
+            if source_row is None or source_row["status"] != "active":
+                continue
+            source_id = int(source_row["id"])
+            if row_hashes[source_id] == memory.content_sha256:
+                continue
+            tier = (
+                "high"
+                if source_row["risk_tier"] == "high"
+                else classify_risk(memory.content, memory.memory_type)
+            )
+            if tier == "high" and available_duplicate(memory.content_sha256) is None:
+                pending_changes.append(
+                    (row_hashes[source_id], memory.content_sha256)
+                )
+        pending_old_hashes = {old_hash for old_hash, _ in pending_changes}
+        if any(
+            new_hash in pending_old_hashes
+            for _, new_hash in pending_changes
+        ):
+            raise ValueError(
+                "review-gated content dependency must be resolved before import"
+            )
+
+    actions_by_index: dict[int, ImportAction] = {}
+    planned_hashes: set[str] = set()
+    indexed_memories = list(enumerate(memories))
+    for index, memory in indexed_memories:
+        source_row = by_source.get(str(memory.path))
+        if source_row is None:
+            continue
+        source_metadata = json.loads(source_row["metadata_json"])
+        if source_row["memory_type"] != memory.memory_type:
+            raise ValueError(f"auto-memory type changed for {memory.path}")
+        if source_metadata.get("content_sha256") == memory.content_sha256:
+            if _source_metadata_view(source_metadata) == _source_metadata_view(
+                _metadata(memory)
+            ):
+                actions_by_index[index] = ImportAction(
+                    "unchanged", memory, int(source_row["id"])
+                )
+            else:
+                actions_by_index[index] = ImportAction(
+                    "update", memory, int(source_row["id"])
+                )
+                planned_hashes.add(memory.content_sha256)
+            continue
+        duplicate_row = available_duplicate(memory.content_sha256)
+        if duplicate_row is not None:
+            actions_by_index[index] = ImportAction(
+                "duplicate",
+                memory,
+                int(source_row["id"]),
+                int(duplicate_row["id"]),
+            )
+            continue
+        if memory.content_sha256 in planned_hashes:
+            actions_by_index[index] = ImportAction(
+                "duplicate", memory, int(source_row["id"])
+            )
+            continue
+        actions_by_index[index] = ImportAction(
+            "update", memory, int(source_row["id"])
+        )
+        planned_hashes.add(memory.content_sha256)
+
+    for index, memory in indexed_memories:
+        if index in actions_by_index:
+            continue
+        duplicate_row = available_duplicate(memory.content_sha256)
+        if duplicate_row is not None or memory.content_sha256 in planned_hashes:
+            actions_by_index[index] = ImportAction("duplicate", memory)
+            continue
+        actions_by_index[index] = ImportAction("add", memory)
+        planned_hashes.add(memory.content_sha256)
+
+    return [actions_by_index[index] for index in range(len(memories))]
+
+
+def _transfer_pending_predecessors(
+    conn: sqlite3.Connection,
+    pending_ids: set[int],
+    created_by_hash: dict[str, int],
+) -> None:
+    for pending_id in pending_ids:
+        pending = get_memory(conn, pending_id)
+        predecessor_value = pending.metadata.get("pending_supersedes")
+        predecessor_ids = (
+            predecessor_value
+            if isinstance(predecessor_value, list)
+            else [predecessor_value]
+            if predecessor_value is not None
+            else []
+        )
+        remaining = []
+        for predecessor_id in predecessor_ids:
+            predecessor = get_memory(conn, int(predecessor_id))
+            if predecessor is None:
+                raise ValueError(f"memory {predecessor_id} not found")
+            predecessor_hash = predecessor.metadata.get("content_sha256")
+            if not isinstance(predecessor_hash, str):
+                predecessor_hash = hashlib.sha256(
+                    predecessor.content.strip().encode("utf-8")
+                ).hexdigest()
+            successor_id = created_by_hash.get(predecessor_hash)
+            successor = (
+                get_memory(conn, successor_id)
+                if successor_id is not None
+                else None
+            )
+            if (
+                successor is not None
+                and successor.status == "active"
+                and successor.id != predecessor.id
+            ):
+                supersede_memory(
+                    conn,
+                    predecessor.id,
+                    successor.id,
+                    "human",
+                    commit=False,
+                )
+            else:
+                remaining.append(predecessor.id)
+        metadata = dict(pending.metadata)
+        metadata.pop("pending_supersedes", None)
+        if remaining:
+            metadata["pending_supersedes"] = (
+                remaining[0] if len(remaining) == 1 else remaining
+            )
+        conn.execute(
+            "update memories set metadata_json = ? where id = ?",
+            (json.dumps(metadata, sort_keys=True), pending.id),
+        )
+
+
+def execute_auto_memory_import(
+    conn: sqlite3.Connection,
+    actions: list[ImportAction],
+    project: str,
+) -> None:
+    created_by_hash: dict[str, int] = {}
+    pending_ids: set[int] = set()
+    conn.execute("savepoint import_auto_memory")
+    try:
+        for action in actions:
+            if action.kind == "add":
+                written = add_memory(
+                    conn,
+                    action.memory.content,
+                    action.memory.memory_type,
+                    "human",
+                    project_key=project,
+                    metadata=_metadata(action.memory),
+                    commit=False,
+                )
+                if written.status == "active" or action.memory.content_sha256 not in created_by_hash:
+                    created_by_hash[action.memory.content_sha256] = written.id
+                if written.status == "pending":
+                    pending_ids.add(written.id)
+            elif action.kind == "update":
+                written = update_memory(
+                    conn,
+                    action.memory_id,
+                    action.memory.content,
+                    "human",
+                    metadata=_metadata(action.memory),
+                    commit=False,
+                )
+                if written.status == "active" or action.memory.content_sha256 not in created_by_hash:
+                    created_by_hash[action.memory.content_sha256] = written.id
+                if written.status == "pending":
+                    pending_ids.add(written.id)
+
+        for action in actions:
+            if action.kind != "duplicate" or action.memory_id is None:
+                continue
+            old = get_memory(conn, action.memory_id)
+            if old is not None and old.status == "superseded":
+                continue
+            successor_id = created_by_hash.get(
+                action.memory.content_sha256
+            ) or action.duplicate_id
+            if successor_id is None:
+                raise ValueError(
+                    f"duplicate successor not found for {action.memory.path}"
+                )
+            supersede_memory(
+                conn,
+                action.memory_id,
+                successor_id,
+                "human",
+                commit=False,
+            )
+            successor = get_memory(conn, successor_id)
+            if successor is not None and successor.status == "pending":
+                pending_ids.add(successor.id)
+
+        _transfer_pending_predecessors(
+            conn,
+            pending_ids,
+            created_by_hash,
+        )
+        conn.execute("release savepoint import_auto_memory")
+        conn.commit()
+    except Exception:
+        conn.execute("rollback to savepoint import_auto_memory")
+        conn.execute("release savepoint import_auto_memory")
+        raise

claude_memory_lab/cjk_glossary.py

@@ -0,0 +1,197 @@
+"""Chinese-to-English query bridge for a lexical, English-language store.
+
+Memories are written in English while the questions are asked in Chinese, so a
+pure-CJK query has nothing to match: FTS5 yields no terms for it, and the
+`content LIKE '%term%'` fallback finds no Chinese inside an English memory.
+Measured on the live store, that made Chinese questions fail outright.
+
+This maps the recurring Chinese vocabulary onto the English words the memories
+actually use, and appends the expansions to the query before it is tokenized.
+It is deliberately a hand-maintained lookup rather than embeddings or a
+translation call: it costs nothing at query time, is deterministic, and its
+effect is measurable by `eval/memory-v2.json`.
+
+Keys are matched as substrings, so Traditional and Simplified forms are listed
+separately, and every key is at least two characters: single characters fire
+inside unrelated words (打掃 -> scan, 封鎖 -> lock) and were measured to add no
+recall. Terms were taken from the 120 most recent real Chinese queries in
+query_log plus the phrasings in the retrieval eval; general question vocabulary
+is preferred over proper nouns, which would only fit the eval.
+
+ponytail: expansions are appended unbounded. Measured ceiling — a pathological
+query containing every key expands to ~260 FTS terms and still returns in under
+30 ms; a realistic long Chinese prompt takes a few ms. Flat OR chains of 10000
+terms were also measured to run fine, so there is no depth limit to respect —
+add a cap only if query latency actually regresses.
+
+Entries that are generic enough to appear in almost any sentence (自動, 完整,
+實際, 安全, 版本 ...) are deliberately absent: they expanded into terms that
+matched unrelated memories and doubled the hard-negative false-positive rate
+without adding any recall.
+"""
+GLOSSARY = {
+    # retrieval / memory domain
+    "記憶": "memory memories",
+    "记忆": "memory memories",
+    "搜尋": "search retrieval",
+    "搜索": "search retrieval",
+    "檢索": "retrieval search",
+    "注入": "inject injection",
+    "相關性": "relevance",
+    "門檻": "threshold cutoff",
+    "阈值": "threshold cutoff",
+    "分數": "score scores scoring",
+    "分数": "score scores scoring",
+    "排序": "rank ranking sort",
+    "過濾": "filter",
+    "筆記": "note notes",
+    "笔记": "note notes",
+    "索引": "index",
+    "快取": "cache",
+    "缓存": "cache",
+    # engineering verbs / nouns
+    "測試": "test tests testing",
+    "测试": "test tests testing",
+    "問題": "issue issues problem problems bug bugs",
+    "问题": "issue issues problem problems bug bugs",
+    "代碼": "code",
+    "代码": "code",
+    "程式碼": "code",
+    "執行": "run execute",
+    "执行": "run execute",
+    "驗收": "acceptance verify",
+    "验收": "acceptance verify",
+    "結果": "result",
+    "结果": "result",
+    "專案": "project projects",
+    "项目": "project projects",
+    "設定": "config setting",
+    "设定": "config setting",
+    "配置": "config configuration",
+    "資料": "data",
+    "数据": "data",
+    "資料庫": "database",
+    "数据库": "database",
+    "確認": "confirm verify",
+    "确认": "confirm verify",
+    "檢查": "check",
+    "检查": "check",
+    "實作": "implement implementation",
+    "实现": "implement implementation",
+    "合併": "merge",
+    "流程": "workflow process",
+    "規格": "spec specification",
+    "规格": "spec specification",
+    "契約": "contract",
+    "契约": "contract",
+    "約束": "constraint",
+    "约束": "constraint",
+    "風險": "risk",
+    "风险": "risk",
+    "行為": "behavior",
+    "行为": "behavior",
+    "狀態": "status state",
+    "状态": "status state",
+    "架構": "architecture",
+    "效能": "performance",
+    "性能": "performance",
+    "權限": "permission",
+    "備份": "backup",
+    "遷移": "migration migrate",
+    "迁移": "migration migrate",
+    "部署": "deploy deploys deployment",
+    "回滾": "rollback",
+    "發布": "release publish",
+    "提交": "commit",
+    "分支": "branch",
+    "標籤": "label tag",
+    "欄位": "column columns field fields",
+    "監控": "monitor",
+    "指標": "metric",
+    "警報": "alert",
+    "逾時": "timeout",
+    "重試": "retry",
+    "併發": "concurrency concurrent",
+    "憑證": "credential",
+    "登入": "login authenticate",
+    "端點": "endpoint",
+    "請求": "request",
+    "回應": "response",
+    "迴圈": "loop",
+    "循环": "loop",
+    "清單": "list",
+    "決定": "decision decisions decide decided",
+    "决定": "decision decisions decide decided",
+    "錯誤": "error errors bug bugs",
+    "错误": "error errors bug bugs",
+    "修法": "fix option approach",
+    "修復": "fix fixes fixed repair",
+    "修复": "fix fixes fixed repair",
+    "實測": "measured verified",
+    "編碼": "encoding",
+    "编码": "encoding",
+    # general vocabulary that recurs in questions rather than in answers
+    "原因": "cause reason root cause",
+    "模組": "module modules",
+    "模块": "module",
+    "檔案": "file files",
+    "文件": "file document",
+    "內容": "content",
+    "内容": "content",
+    "證明": "proof prove evidence",
+    "证明": "proof prove evidence",
+    "候選": "candidate",
+    "回傳": "return returns",
+    "返回": "return returns",
+    "結論": "conclusion conclude",
+    "分析": "analysis analyze",
+    "可靠": "reliable trust sound",
+    "相信": "trust",
+    "內建": "bundled built-in",
+    "内置": "bundled built-in",
+    "標示": "flag label",
+    "解決": "resolve fix",
+    "解决": "resolve fix",
+    "限制": "limit limits constraint constraints ceiling",
+    "重複": "duplicate repeated",
+    "重复": "duplicate repeated",
+    "順序": "order ordering",
+    "範圍": "scope range",
+    "范围": "scope range",
+    # project-specific vocabulary
+    "卡片": "card cards",
+    "掃描": "scan scanner",
+    "扫描": "scan scanner",
+    "辨識": "recognition identify OCR",
+    "识别": "recognition identify OCR",
+    "圖像": "image",
+    "图像": "image",
+    "裁切": "crop",
+    "權益": "equity",
+    "帳戶": "account",
+    "账户": "account",
+    "槓桿": "leverage",
+    "杠杆": "leverage",
+    "部位": "position sizing",
+    "策略": "strategy",
+    "交易": "trade trading",
+}
+
+
+def expand_cjk_query(query: str) -> str:
+    """Append English equivalents for the Chinese terms present in the query.
+
+    Returns the query unchanged when it contains no known Chinese term, so
+    English queries keep their exact current behaviour.
+    """
+    words = [
+        word
+        for chinese, english in GLOSSARY.items()
+        if chinese in query
+        for word in english.split()
+    ]
+    if not words:
+        return query
+    # Deduplicate: FTS5 really does double-count a repeated term, and overlapping
+    # entries (資料/資料庫, 問題/錯誤 both yielding "bug") would silently weight it.
+    return f"{query} {' '.join(dict.fromkeys(words))}"