keepm 0.2.0__py3-none-any.whl

keepm/doctor.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from keepm.database import MemoryDatabase
+from keepm.markdown import parse_memory
+from keepm.storage import MemoryStorage
+from keepm.sync import sha256_file
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorFinding:
+    code: str
+    path: Path | None
+    message: str
+    severity: str = "error"
+
+
+def _expected_scope(storage: MemoryStorage, path: Path) -> str | None:
+    relative = path.resolve().relative_to(storage.config.memory_root.resolve())
+    if len(relative.parts) >= 2 and relative.parts[0] == "global":
+        return "global"
+    if len(relative.parts) >= 3 and relative.parts[0] == "projects":
+        return relative.parts[1]
+    return None
+
+
+def run_doctor(
+    storage: MemoryStorage, database: MemoryDatabase
+) -> tuple[DoctorFinding, ...]:
+    findings: list[DoctorFinding] = []
+    paths = set(storage.discover())
+    records = database.all_records()
+    records_by_path = {record.path: record for record in records}
+    records_by_id = {record.id: record for record in records}
+    parsed_by_path = {}
+
+    for path in sorted(paths):
+        try:
+            document = parse_memory(path, path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, ValueError) as error:
+            findings.append(
+                DoctorFinding("invalid_markdown", path, str(error), "error")
+            )
+            continue
+        parsed_by_path[path] = document
+        expected = _expected_scope(storage, path)
+        if expected is None or document.scope != expected:
+            findings.append(
+                DoctorFinding(
+                    "scope_path_mismatch",
+                    path,
+                    f"frontmatter scope {document.scope!r} does not match directory "
+                    f"scope {expected!r}",
+                    "error",
+                )
+            )
+
+    ids: dict[str, list[Path]] = {}
+    names: dict[tuple[str, str], list[Path]] = {}
+    for path, document in parsed_by_path.items():
+        ids.setdefault(document.id, []).append(path)
+        names.setdefault((document.scope, document.name.casefold()), []).append(path)
+    for memory_id, duplicate_paths in ids.items():
+        if len(duplicate_paths) > 1:
+            for path in duplicate_paths:
+                findings.append(
+                    DoctorFinding(
+                        "duplicate_id",
+                        path,
+                        f"memory id {memory_id!r} appears in {len(duplicate_paths)} files",
+                    )
+                )
+    for (scope, name), duplicate_paths in names.items():
+        if len(duplicate_paths) > 1:
+            for path in duplicate_paths:
+                findings.append(
+                    DoctorFinding(
+                        "duplicate_name",
+                        path,
+                        f"memory name {name!r} appears {len(duplicate_paths)} times "
+                        f"in scope {scope!r}",
+                    )
+                )
+
+    for path in sorted(set(parsed_by_path) - set(records_by_path)):
+        findings.append(
+            DoctorFinding(
+                "markdown_only", path, "valid Markdown file is absent from SQLite"
+            )
+        )
+    for path in sorted(set(records_by_path) - paths):
+        findings.append(
+            DoctorFinding("index_only", path, "SQLite row points to a missing file")
+        )
+    for path in sorted(set(parsed_by_path) & set(records_by_path)):
+        try:
+            checksum = sha256_file(path)
+        except OSError as error:
+            findings.append(DoctorFinding("unreadable_file", path, str(error)))
+            continue
+        if checksum != records_by_path[path].checksum:
+            findings.append(
+                DoctorFinding(
+                    "checksum_divergence",
+                    path,
+                    "Markdown checksum differs from the SQLite index",
+                )
+            )
+
+    for source_id, target_text, relation_type in database.unresolved_links():
+        source = records_by_id.get(source_id)
+        findings.append(
+            DoctorFinding(
+                "unresolved_link",
+                source.path if source else None,
+                f"{relation_type} WikiLink target {target_text!r} is unresolved",
+                "warning",
+            )
+        )
+
+    severity_order = {"error": 0, "warning": 1, "info": 2}
+    findings.sort(
+        key=lambda item: (
+            severity_order.get(item.severity, 9),
+            item.code,
+            str(item.path or ""),
+        )
+    )
+    return tuple(findings)

keepm/instructions.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from keepm.config import MemoryLanguage
+from keepm.integrations import McpTarget
+
+START_MARKER = "<!-- keepm:start -->"
+END_MARKER = "<!-- keepm:end -->"
+LEGACY_START_MARKER = "<!-- KeepM Memory: begin -->"
+LEGACY_END_MARKER = "<!-- KeepM Memory: end -->"
+
+
+class InstructionError(RuntimeError):
+    """An Agent instruction file cannot be updated without risking user content."""
+
+
+@dataclass(frozen=True, slots=True)
+class InstructionResult:
+    target: McpTarget
+    path: Path | None
+    status: Literal["created", "updated", "unchanged", "failed"]
+    detail: str
+
+
+EN_PROTOCOL = """## KeepM memory protocol
+
+Use KeepM for durable memory when its MCP tools are available. Write new memory names, descriptions, and prose in English; keep code, paths, API names, and exact protocol labels unchanged.
+
+### At task start
+
+1. Call `memory_context` once with a concise description of the current task.
+2. Use `memory_search` and `memory_read` only when that context is insufficient. Do not load the whole Vault.
+3. Do not call `memory_sync` routinely.
+
+### While working
+
+- Treat Markdown in the configured Vault as the source of truth.
+- Before updating an existing memory, read it and pass its checksum as `expected_checksum`.
+- Do not store tentative hypotheses, routine progress, raw logs, secrets, tokens, or large code dumps.
+
+### Before completing a task
+
+Write a memory directly with `memory_write` only when the result will be useful in a future session:
+
+- a stable user preference or workflow rule;
+- feedback that should prevent a repeated mistake;
+- a project architecture decision, invariant, or important constraint;
+- a reusable diagnosis and fix for a likely recurring problem;
+- a stable project reference needed by future work.
+
+Search first when an overlapping memory may exist; update it instead of creating a duplicate. Use `global` for cross-project preferences and workflows, and `project` for repository-specific knowledge. For `feedback` and `project` memories, include the exact labels `Why:` and `How to apply:`. Prefer one concise, actionable memory over several overlapping memories. Do not save routine implementations, temporary workarounds, task status, or facts already covered by memory.
+
+### Indexing and recovery
+
+- `memory_write` and `memory_delete` update the affected SQLite index immediately; do not call `memory_sync` after them.
+- KeepM reconciles at MCP startup. Context, search, and read tools also refresh a stale index, while the watcher normally handles Obsidian edits.
+- Use `memory_sync(full=false)` only after bulk external changes, watcher failure, or suspected mismatch.
+- Use `memory_doctor` to diagnose problems and `memory_sync(full=true)` only to repair or rebuild the derived index."""
+
+
+ZH_PROTOCOL = """## KeepM 记忆协议
+
+当 KeepM MCP 工具可用时，用它管理长期记忆。新记忆的名称、描述和正文默认使用中文；代码、路径、API 名称和协议要求的固定标签保持原文。
+
+### 任务开始时
+
+1. 使用当前任务的简短描述调用一次 `memory_context`。
+2. 只有返回的上下文不足时才调用 `memory_search` 和 `memory_read`，不要把整个 Vault 读入上下文。
+3. 正常情况下不要调用 `memory_sync`。
+
+### 工作过程中
+
+- 将配置 Vault 中的 Markdown 视为唯一真源。
+- 更新已有记忆前先读取它，并把返回的 checksum 作为 `expected_checksum`。
+- 不记录尚未验证的猜测、普通进度、原始日志、密钥、令牌或大段代码。
+
+### 任务完成前
+
+仅当结果对未来会话仍有价值时，才直接调用 `memory_write`：
+
+- 稳定的用户偏好或工作流规则；
+- 能避免重复犯错的用户反馈；
+- 项目架构决策、不变量或重要约束；
+- 可能再次遇到的问题及可复用的诊断和修复方法；
+- 后续工作需要的稳定项目资料。
+
+如果可能已有相同主题的记忆，先搜索并更新原记忆，避免重复创建。跨项目偏好和工作流使用 `global`，仓库专属知识使用 `project`。`feedback` 和 `project` 记忆必须包含固定标签 `Why:` 与 `How to apply:`。优先记录一条简洁、可执行的记忆，不要拆成多条重叠内容。不要保存常规实现、临时方案、任务状态或已有记忆覆盖的事实。
+
+### 索引与恢复
+
+- `memory_write` 和 `memory_delete` 会立即更新对应 SQLite 索引，之后不要调用 `memory_sync`。
+- KeepM 会在 MCP 启动时对账；上下文、搜索和读取工具也会刷新过期索引，Obsidian 修改通常由 watcher 处理。
+- 只有批量外部修改、watcher 失败或怀疑不一致时，才使用 `memory_sync(full=false)`。
+- 先用 `memory_doctor` 诊断；只有修复或重建派生索引时才使用 `memory_sync(full=true)`。"""
+
+
+def render_managed_block(language: MemoryLanguage) -> str:
+    if language == "en":
+        protocol = EN_PROTOCOL
+    elif language == "zh":
+        protocol = ZH_PROTOCOL
+    else:
+        raise ValueError("language must be 'zh' or 'en'")
+    return f"{START_MARKER}\n\n{protocol.strip()}\n\n{END_MARKER}"
+
+
+def instruction_path(target: McpTarget, home: Path) -> Path:
+    resolved_home = home.expanduser().resolve()
+    if target.scope == "user":
+        if target.agent == "codex":
+            return resolved_home / ".codex" / "AGENTS.md"
+        return resolved_home / ".claude" / "CLAUDE.md"
+
+    assert target.project_dir is not None
+    if target.agent == "codex":
+        return target.project_dir / "AGENTS.md"
+    return target.project_dir / "CLAUDE.md"
+
+
+def _managed_span(content: str, path: Path) -> tuple[int, int] | None:
+    pairs = (
+        (START_MARKER, END_MARKER),
+        (LEGACY_START_MARKER, LEGACY_END_MARKER),
+    )
+    active: list[tuple[str, str]] = []
+    for start, end in pairs:
+        start_count = content.count(start)
+        end_count = content.count(end)
+        if start_count or end_count:
+            if start_count != 1 or end_count != 1:
+                raise InstructionError(f"malformed KeepM markers in {path}")
+            active.append((start, end))
+    if not active:
+        return None
+    if len(active) != 1:
+        raise InstructionError(f"multiple KeepM marker formats in {path}")
+    start_marker, end_marker = active[0]
+    start_index = content.index(start_marker)
+    end_index = content.index(end_marker)
+    if start_index >= end_index:
+        raise InstructionError(f"reversed KeepM markers in {path}")
+    return start_index, end_index + len(end_marker)
+
+
+def _replace_or_append(content: str, block: str, path: Path) -> str:
+    newline = "\r\n" if "\r\n" in content else "\n"
+    localized_block = block.replace("\n", newline)
+    span = _managed_span(content, path)
+    if span is not None:
+        start, end = span
+        updated = content[:start] + localized_block + content[end:]
+        return updated if updated.endswith(("\n", "\r")) else updated + newline
+    if not content:
+        return localized_block + newline
+    separator = "" if content.endswith(newline * 2) else newline if content.endswith(newline) else newline * 2
+    return content + separator + localized_block + newline
+
+
+class InstructionInstaller:
+    def __init__(self, *, home: Path | None = None) -> None:
+        self.home = (home or Path.home()).expanduser().resolve()
+
+    def install(
+        self, target: McpTarget, language: MemoryLanguage
+    ) -> InstructionResult:
+        path = instruction_path(target, self.home)
+        block = render_managed_block(language)
+        try:
+            migrated = self._remove_nested_claude_block(target)
+            exists = path.is_file()
+            content = path.read_bytes().decode("utf-8") if exists else ""
+            updated = _replace_or_append(content, block, path)
+            if updated == content:
+                return InstructionResult(target, path, "unchanged", "KeepM instructions already match")
+
+            mode = stat.S_IMODE(path.stat().st_mode) if exists else None
+            path.parent.mkdir(parents=True, exist_ok=True)
+            temporary = path.with_name(f".{path.name}.keepm.tmp")
+            temporary.write_bytes(updated.encode("utf-8"))
+            if mode is not None:
+                temporary.chmod(mode)
+            os.replace(temporary, path)
+            status: Literal["created", "updated"] = "updated" if exists else "created"
+            detail = f"{status} KeepM instructions"
+            if migrated:
+                detail += "; migrated old .claude/CLAUDE.md block"
+            return InstructionResult(target, path, status, detail)
+        except InstructionError:
+            raise
+        except (OSError, UnicodeDecodeError) as error:
+            raise InstructionError(f"cannot update Agent instructions {path}: {error}") from error
+
+    def _remove_nested_claude_block(self, target: McpTarget) -> bool:
+        if target.agent != "claude" or target.scope != "project":
+            return False
+        assert target.project_dir is not None
+        nested = target.project_dir / ".claude" / "CLAUDE.md"
+        if not nested.is_file():
+            return False
+        try:
+            content = nested.read_bytes().decode("utf-8")
+            span = _managed_span(content, nested)
+            if span is None:
+                return False
+            start, end = span
+            updated = content[:start] + content[end:]
+            if not updated.strip():
+                nested.unlink()
+                return True
+            mode = stat.S_IMODE(nested.stat().st_mode)
+            temporary = nested.with_name(f".{nested.name}.keepm.tmp")
+            temporary.write_bytes(updated.encode("utf-8"))
+            temporary.chmod(mode)
+            os.replace(temporary, nested)
+            return True
+        except InstructionError:
+            raise
+        except (OSError, UnicodeDecodeError) as error:
+            raise InstructionError(
+                f"cannot migrate old Agent instructions {nested}: {error}"
+            ) from error

keepm/integrations.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import tomlkit
+
+AgentName = Literal["codex", "claude"]
+McpScope = Literal["user", "project"]
+
+SERVER_COMMAND = "uvx"
+SERVER_ARGS = ("--from", "keepm", "keepm")
+CODEX_SERVER = {
+    "type": "stdio",
+    "command": SERVER_COMMAND,
+    "args": list(SERVER_ARGS),
+}
+CLAUDE_SERVER = {"command": SERVER_COMMAND, "args": list(SERVER_ARGS)}
+
+
+class IntegrationError(RuntimeError):
+    """An Agent CLI or its configuration could not be safely updated."""
+
+
+class RegistrationConflict(IntegrationError):
+    """A named KeepM registration exists but differs from the expected one."""
+
+
+@dataclass(frozen=True, slots=True)
+class McpTarget:
+    agent: AgentName
+    scope: McpScope
+    project_dir: Path | None = None
+
+    def __post_init__(self) -> None:
+        if self.agent not in ("codex", "claude"):
+            raise ValueError(f"unsupported Agent: {self.agent}")
+        if self.scope not in ("user", "project"):
+            raise ValueError(f"unsupported MCP scope: {self.scope}")
+        if self.scope == "project":
+            if self.project_dir is None:
+                raise ValueError("project_dir is required for project-scoped MCP setup")
+            object.__setattr__(
+                self, "project_dir", self.project_dir.expanduser().resolve()
+            )
+        elif self.project_dir is not None:
+            object.__setattr__(
+                self, "project_dir", self.project_dir.expanduser().resolve()
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class RegistrationState:
+    kind: Literal["missing", "equivalent", "different"]
+    detail: str
+
+
+@dataclass(frozen=True, slots=True)
+class CommandResult:
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+
+Runner = Callable[[Sequence[str], Path | None], CommandResult]
+Which = Callable[[str], str | None]
+
+
+def _run_subprocess(command: Sequence[str], cwd: Path | None) -> CommandResult:
+    try:
+        result = subprocess.run(
+            list(command),
+            cwd=cwd,
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=15,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired) as error:
+        raise IntegrationError(f"cannot run {' '.join(command)}: {error}") from error
+    return CommandResult(result.returncode, result.stdout, result.stderr)
+
+
+def _is_expected(record: Mapping[str, object], expected: Mapping[str, object]) -> bool:
+    if record.get("command") != expected["command"]:
+        return False
+    args = record.get("args")
+    if not isinstance(args, list) or args != expected["args"]:
+        return False
+    expected_type = expected.get("type")
+    return expected_type is None or record.get("type") == expected_type
+
+
+class AgentRegistrar:
+    """Inspect and register the one canonical KeepM stdio command."""
+
+    def __init__(
+        self,
+        *,
+        home: Path | None = None,
+        which: Which = shutil.which,
+        run: Runner = _run_subprocess,
+    ) -> None:
+        self.home = (home or Path.home()).expanduser().resolve()
+        self._which = which
+        self._run = run
+
+    def available_agents(self) -> tuple[AgentName, ...]:
+        agents: list[AgentName] = []
+        for agent in ("codex", "claude"):
+            if self._which(agent):
+                agents.append(agent)
+        return tuple(agents)
+
+    def has_uvx(self) -> bool:
+        return self._which("uvx") is not None
+
+    def inspect(self, target: McpTarget) -> RegistrationState:
+        if target.agent == "codex" and target.scope == "user":
+            return self._inspect_codex_user()
+        if target.agent == "codex":
+            return self._inspect_codex_project(target)
+        return self._inspect_claude(target)
+
+    def apply(self, target: McpTarget, *, replace: bool = False) -> RegistrationState:
+        if not self._which(target.agent):
+            raise IntegrationError(f"{target.agent} is not available on PATH")
+        state = self.inspect(target)
+        if state.kind == "equivalent":
+            return state
+        if state.kind == "different" and not replace:
+            raise RegistrationConflict(state.detail)
+
+        if target.agent == "codex" and target.scope == "project":
+            self._write_codex_project(target)
+            return self.inspect(target)
+
+        if state.kind == "different":
+            self._run_checked(self._remove_command(target), target.project_dir)
+        self._run_checked(self._add_command(target), target.project_dir)
+        updated = self.inspect(target)
+        if updated.kind != "equivalent":
+            raise IntegrationError(
+                f"{target.agent} accepted the KeepM command but did not save the expected configuration"
+            )
+        return updated
+
+    def _inspect_codex_user(self) -> RegistrationState:
+        result = self._run(["codex", "mcp", "get", "keepm", "--json"], None)
+        if result.returncode != 0:
+            return RegistrationState("missing", "Codex has no user-level keepm MCP")
+        try:
+            payload = json.loads(result.stdout)
+            transport = payload["transport"]
+        except (json.JSONDecodeError, KeyError, TypeError) as error:
+            raise IntegrationError(f"cannot read Codex keepm configuration: {error}") from error
+        if isinstance(transport, dict) and _is_expected(transport, CODEX_SERVER):
+            return RegistrationState("equivalent", "Codex user MCP already matches KeepM")
+        return RegistrationState("different", "Codex user MCP named keepm uses another command")
+
+    def _inspect_codex_project(self, target: McpTarget) -> RegistrationState:
+        config_path = self._codex_project_path(target)
+        if not config_path.is_file():
+            return RegistrationState("missing", f"missing {config_path}")
+        try:
+            document = tomlkit.parse(config_path.read_text(encoding="utf-8"))
+            servers = document.get("mcp_servers", {})
+            record = servers.get("keepm") if isinstance(servers, Mapping) else None
+        except (OSError, tomlkit.exceptions.ParseError) as error:
+            raise IntegrationError(f"cannot read Codex project config {config_path}: {error}") from error
+        if record is None:
+            return RegistrationState("missing", f"{config_path} has no keepm MCP")
+        if isinstance(record, Mapping) and _is_expected(record, CODEX_SERVER):
+            return RegistrationState("equivalent", "Codex project MCP already matches KeepM")
+        return RegistrationState("different", "Codex project MCP named keepm uses another command")
+
+    def _inspect_claude(self, target: McpTarget) -> RegistrationState:
+        config_path = self._claude_path(target)
+        if not config_path.is_file():
+            return RegistrationState("missing", f"missing {config_path}")
+        try:
+            payload = json.loads(config_path.read_text(encoding="utf-8"))
+            servers = payload.get("mcpServers", {})
+            record = servers.get("keepm") if isinstance(servers, dict) else None
+        except (OSError, json.JSONDecodeError) as error:
+            raise IntegrationError(f"cannot read Claude Code config {config_path}: {error}") from error
+        if record is None:
+            return RegistrationState("missing", f"{config_path} has no keepm MCP")
+        if isinstance(record, dict) and _is_expected(record, CLAUDE_SERVER):
+            return RegistrationState("equivalent", "Claude Code MCP already matches KeepM")
+        return RegistrationState("different", "Claude Code MCP named keepm uses another command")
+
+    def _write_codex_project(self, target: McpTarget) -> None:
+        config_path = self._codex_project_path(target)
+        try:
+            if config_path.is_file():
+                document = tomlkit.parse(config_path.read_text(encoding="utf-8"))
+            else:
+                document = tomlkit.document()
+            servers = document.get("mcp_servers")
+            if servers is None:
+                servers = tomlkit.table()
+                document["mcp_servers"] = servers
+            if not isinstance(servers, Mapping):
+                raise IntegrationError(
+                    f"cannot update {config_path}: mcp_servers is not a TOML table"
+                )
+            keepm = tomlkit.table()
+            keepm.add("type", "stdio")
+            keepm.add("command", SERVER_COMMAND)
+            keepm.add("args", list(SERVER_ARGS))
+            servers["keepm"] = keepm
+            config_path.parent.mkdir(parents=True, exist_ok=True)
+            temporary = config_path.with_suffix(config_path.suffix + ".tmp")
+            temporary.write_text(tomlkit.dumps(document), encoding="utf-8", newline="\n")
+            os.replace(temporary, config_path)
+        except (OSError, tomlkit.exceptions.ParseError) as error:
+            raise IntegrationError(f"cannot update Codex project config {config_path}: {error}") from error
+
+    def _add_command(self, target: McpTarget) -> list[str]:
+        prefix = [target.agent, "mcp", "add"]
+        if target.agent == "claude":
+            prefix.extend(["--scope", target.scope])
+        return [*prefix, "keepm", "--", SERVER_COMMAND, *SERVER_ARGS]
+
+    def _remove_command(self, target: McpTarget) -> list[str]:
+        prefix = [target.agent, "mcp", "remove"]
+        if target.agent == "claude":
+            prefix.extend(["--scope", target.scope])
+        return [*prefix, "keepm"]
+
+    def _run_checked(self, command: Sequence[str], cwd: Path | None) -> None:
+        result = self._run(command, cwd)
+        if result.returncode == 0:
+            return
+        detail = (result.stderr or result.stdout).strip() or "unknown error"
+        raise IntegrationError(f"{' '.join(command)} failed: {detail}")
+
+    def _codex_project_path(self, target: McpTarget) -> Path:
+        assert target.project_dir is not None
+        return target.project_dir / ".codex" / "config.toml"
+
+    def _claude_path(self, target: McpTarget) -> Path:
+        if target.scope == "user":
+            return self.home / ".claude.json"
+        assert target.project_dir is not None
+        return target.project_dir / ".mcp.json"