keepm 0.2.0__py3-none-any.whl

keepm/service.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import datetime as dt
+import uuid
+from pathlib import Path
+
+from keepm.config import KeepMConfig
+from keepm.database import IndexedMemory, MemoryDatabase
+from keepm.doctor import DoctorFinding, run_doctor
+from keepm.markdown import parse_memory, render_memory, slug_filename
+from keepm.models import MemoryDocument, SearchHit, SyncReport
+from keepm.projects import resolve_project_name
+from keepm.storage import MemoryStorage
+from keepm.sync import SyncEngine, sha256_file
+
+
+class ConcurrentUpdateError(RuntimeError):
+    pass
+
+
+class IndexSyncError(RuntimeError):
+    pass
+
+
+class MemoryService:
+    def __init__(
+        self,
+        config: KeepMConfig,
+        storage: MemoryStorage,
+        database: MemoryDatabase,
+        sync_engine: SyncEngine,
+    ) -> None:
+        self.config = config
+        self.storage = storage
+        self.database = database
+        self.sync_engine = sync_engine
+        self._freshness_lock = asyncio.Lock()
+
+    @staticmethod
+    def _new_id() -> str:
+        uuid7 = getattr(uuid, "uuid7", None)
+        return str(uuid7() if uuid7 else uuid.uuid4())
+
+    @staticmethod
+    def _project(workspace: Path) -> str:
+        return resolve_project_name(workspace.resolve())
+
+    def _scope_name(self, workspace: Path, scope: str) -> str:
+        if scope == "global":
+            return "global"
+        if scope == "project":
+            return self._project(workspace)
+        raise ValueError("scope must be 'global' or 'project'")
+
+    def _query_scopes(self, workspace: Path, scope: str | None = None) -> tuple[str, ...]:
+        project = self._project(workspace)
+        if scope is None:
+            return (project, "global")
+        if scope == "project":
+            return (project,)
+        if scope == "global":
+            return ("global",)
+        raise ValueError("scope must be 'global', 'project', or omitted")
+
+    @staticmethod
+    def _apply_project_override(
+        hits: tuple[SearchHit, ...], project: str
+    ) -> tuple[SearchHit, ...]:
+        project_names = {
+            hit.name.casefold() for hit in hits if hit.scope == project
+        }
+        seen_ids: set[str] = set()
+        filtered: list[SearchHit] = []
+        for hit in hits:
+            if hit.id in seen_ids:
+                continue
+            if hit.scope == "global" and hit.name.casefold() in project_names:
+                continue
+            seen_ids.add(hit.id)
+            filtered.append(hit)
+        return tuple(filtered)
+
+    def search(
+        self,
+        *,
+        workspace: Path,
+        query: str,
+        scope: str | None = None,
+        limit: int = 10,
+    ) -> tuple[SearchHit, ...]:
+        project = self._project(workspace)
+        scopes = self._query_scopes(workspace, scope)
+        hits = self.database.search(query, scopes=scopes, limit=max(limit * 2, limit))
+        if scope is None:
+            hits = self._apply_project_override(hits, project)
+        return hits[: max(limit, 0)]
+
+    def context(
+        self,
+        *,
+        workspace: Path,
+        query: str,
+        limit: int = 10,
+        max_chars: int = 6_000,
+    ) -> tuple[SearchHit, ...]:
+        if limit < 1 or max_chars < 1:
+            return ()
+        project = self._project(workspace)
+        scopes = (project, "global")
+        pinned = self.database.list_pinned(scopes=scopes, limit=limit * 2)
+        ranked = self.database.search(query, scopes=scopes, limit=limit * 2)
+        merged = self._apply_project_override(pinned + ranked, project)
+
+        bounded: list[SearchHit] = []
+        used = 0
+        for hit in merged:
+            if len(bounded) >= limit or used >= max_chars:
+                break
+            remaining = max_chars - used
+            snippet = hit.snippet[:remaining]
+            if not snippet:
+                break
+            bounded.append(dataclasses.replace(hit, snippet=snippet))
+            used += len(snippet)
+        return tuple(bounded)
+
+    def _lookup_record(self, workspace: Path, identifier: str) -> IndexedMemory:
+        scopes = self._query_scopes(workspace)
+        record = self.database.get_by_id(identifier)
+        if record is None:
+            record = self.database.get_by_name(identifier, scopes=scopes)
+        if record is None and ("/" in identifier or identifier.endswith(".md")):
+            candidate = Path(identifier)
+            if not candidate.is_absolute():
+                candidate = self.config.memory_root / candidate
+            safe_path = self.storage.require_safe_path(candidate)
+            record = self.database.get_by_path(safe_path)
+        if record is None:
+            raise LookupError(f"memory not found: {identifier}")
+        if record.scope not in scopes:
+            raise LookupError(f"memory is outside the active scopes: {identifier}")
+        return record
+
+    def read(self, *, workspace: Path, identifier: str) -> MemoryDocument:
+        document, _ = self.read_with_checksum(
+            workspace=workspace, identifier=identifier
+        )
+        return document
+
+    def read_with_checksum(
+        self, *, workspace: Path, identifier: str
+    ) -> tuple[MemoryDocument, str]:
+        record = self._lookup_record(workspace, identifier)
+        try:
+            document = parse_memory(
+                record.path, record.path.read_text(encoding="utf-8")
+            )
+        except OSError as error:
+            raise LookupError(f"memory file is unavailable: {record.path}") from error
+        return document, record.checksum
+
+    def write(
+        self,
+        *,
+        workspace: Path,
+        scope: str,
+        name: str,
+        description: str,
+        memory_type: str,
+        body: str,
+        tags: tuple[str, ...] = (),
+        pinned: bool = False,
+        expected_checksum: str | None = None,
+    ) -> MemoryDocument:
+        target_scope = self._scope_name(workspace, scope)
+        logical_name = slug_filename(name).removesuffix(".md")
+        existing = self.database.get_by_name(logical_name, scopes=(target_scope,))
+        if expected_checksum is not None:
+            if existing is None or not existing.path.is_file():
+                raise ConcurrentUpdateError("memory changed on disk or no longer exists")
+            if sha256_file(existing.path) != expected_checksum:
+                raise ConcurrentUpdateError("memory changed on disk since it was read")
+
+        if existing:
+            target = existing.path
+            memory_id = existing.id
+            created = existing.created
+        else:
+            target = self.storage.path_for(
+                scope=target_scope, filename=slug_filename(logical_name)
+            )
+            if target.exists():
+                raise FileExistsError(f"unindexed memory file already exists: {target}")
+            memory_id = self._new_id()
+            created = dt.date.today().isoformat()
+
+        today = dt.date.today().isoformat()
+        candidate = MemoryDocument(
+            id=memory_id,
+            name=logical_name,
+            description=description.strip(),
+            type=memory_type,
+            scope=target_scope,
+            created=created,
+            updated=today,
+            body=body.strip(),
+            path=target,
+            tags=tuple(tags),
+            pinned=pinned,
+        )
+        rendered = render_memory(candidate)
+        validated = parse_memory(target, rendered)
+        self.storage.atomic_write(target, rendered)
+        report = self.sync_engine.reconcile_paths((target,))
+        if report.errors:
+            self.database.set_state("dirty", "1")
+            raise IndexSyncError(
+                "Markdown was saved but the SQLite index update failed: "
+                + "; ".join(report.errors)
+            )
+        self.database.set_state("dirty", "0")
+        return validated
+
+    def delete(self, *, workspace: Path, identifier: str) -> Path:
+        record = self._lookup_record(workspace, identifier)
+        trashed = self.storage.soft_delete(record.path)
+        report = self.sync_engine.reconcile_paths((record.path,))
+        if report.errors:
+            self.database.set_state("dirty", "1")
+            raise IndexSyncError(
+                "Markdown was moved to trash but index cleanup failed: "
+                + "; ".join(report.errors)
+            )
+        return trashed
+
+    def links(
+        self, *, workspace: Path, identifier: str, direction: str = "both"
+    ) -> dict[str, object]:
+        if direction not in {"forward", "backward", "both"}:
+            raise ValueError("direction must be 'forward', 'backward', or 'both'")
+        record = self._lookup_record(workspace, identifier)
+        result: dict[str, object] = {"id": record.id}
+        if direction in {"forward", "both"}:
+            result["forward"] = self.database.forward_links(record.id)
+        if direction in {"backward", "both"}:
+            result["backlinks"] = self.database.backlinks(record.id)
+        return result
+
+    def status(self, *, workspace: Path | None = None) -> dict[str, object]:
+        records = self.database.all_records()
+        return {
+            "configured": True,
+            "vault_path": str(self.config.vault_path),
+            "memory_root": str(self.config.memory_root),
+            "language": self.config.language,
+            "project": self._project(workspace) if workspace else None,
+            "database_path": str(self.database.path),
+            "tokenizer": self.database.tokenizer,
+            "memory_count": len(records),
+            "index_error_count": len(self.database.index_errors()),
+            "last_reconcile": self.database.get_state("last_reconcile"),
+            "dirty": self.database.get_state("dirty") == "1",
+        }
+
+    def sync(self, *, full: bool = False) -> SyncReport:
+        report = (
+            self.sync_engine.full_rebuild()
+            if full
+            else self.sync_engine.quick_reconcile()
+        )
+        self.database.set_state("dirty", "1" if report.errors else "0")
+        return report
+
+    def doctor(self) -> tuple[DoctorFinding, ...]:
+        return run_doctor(self.storage, self.database)
+
+    async def ensure_fresh(self) -> SyncReport | None:
+        threshold = self.config.stale_after_seconds
+        last_reconcile = self.database.get_state("last_reconcile")
+        stale = last_reconcile is None
+        if last_reconcile is not None:
+            try:
+                last = dt.datetime.fromisoformat(last_reconcile)
+                if last.tzinfo is None:
+                    last = last.replace(tzinfo=dt.timezone.utc)
+                age = (dt.datetime.now(dt.timezone.utc) - last).total_seconds()
+                stale = age >= threshold
+            except ValueError:
+                stale = True
+        if not stale:
+            return None
+        async with self._freshness_lock:
+            if threshold > 0:
+                refreshed = self.database.get_state("last_reconcile")
+                if refreshed and refreshed != last_reconcile:
+                    return None
+            return self.sync(full=False)

keepm/setup.py

@@ -0,0 +1,405 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, Protocol, cast
+
+import questionary
+
+from keepm.config import ConfigStore, KeepMConfig, MemoryLanguage
+from keepm.instructions import (
+    InstructionError,
+    InstructionInstaller,
+    InstructionResult,
+)
+from keepm.integrations import (
+    AgentName,
+    AgentRegistrar,
+    IntegrationError,
+    McpScope,
+    McpTarget,
+    RegistrationState,
+)
+
+
+class SetupError(RuntimeError):
+    """The requested setup cannot proceed without a user decision."""
+
+
+class Prompt(Protocol):
+    def ask(self, message: str, *, default: str | None = None) -> str: ...
+
+    def choose(
+        self, message: str, choices: Sequence[str], *, default: str
+    ) -> str: ...
+
+
+PROMPT_STYLE = questionary.Style(
+    [
+        ("qmark", "fg:#00afff bold"),
+        ("question", "fg:#5f87ff bold"),
+        ("answer", "fg:#00d787 bold"),
+        ("pointer", "fg:#00d787 bold"),
+        ("highlighted", "fg:#00d787 bold"),
+        ("selected", "fg:#00d7af bold"),
+        ("instruction", "fg:#808080"),
+        ("text", ""),
+        ("disabled", "fg:#666666 italic"),
+    ]
+)
+
+CHOICE_TITLES = {
+    "zh": "中文 (zh)",
+    "en": "English (en)",
+    "codex": "Codex",
+    "claude": "Claude Code",
+    "user": "User scope",
+    "project": "Project scope",
+    "replace": "Replace",
+    "keep": "Keep existing",
+    "skip": "Skip",
+    "cancel": "Cancel",
+}
+
+
+class TerminalPrompt:
+    @staticmethod
+    def _required(answer: object) -> object:
+        if answer is None:
+            raise SetupError("setup cancelled")
+        return answer
+
+    def ask(self, message: str, *, default: str | None = None) -> str:
+        answer = questionary.text(
+            message,
+            default=default or "",
+            qmark="?",
+            style=PROMPT_STYLE,
+        ).ask()
+        return str(self._required(answer)).strip()
+
+    def choose(
+        self, message: str, choices: Sequence[str], *, default: str
+    ) -> str:
+        options = [
+            questionary.Choice(CHOICE_TITLES.get(choice, choice), value=choice)
+            for choice in choices
+        ]
+        answer = questionary.select(
+            message,
+            choices=options,
+            default=default,
+            pointer="❯",
+            qmark="?",
+            style=PROMPT_STYLE,
+            instruction="(↑/↓ move, enter confirm)",
+        ).ask()
+        return str(self._required(answer))
+
+
+
+@dataclass(frozen=True, slots=True)
+class SetupRequest:
+    vault_path: Path | None = None
+    memory_dir: str | None = None
+    language: MemoryLanguage | None = None
+    agent: AgentName | None = None
+    scope: McpScope | None = None
+    project_dir: Path = field(default_factory=Path.cwd)
+    force: bool = False
+    assume_yes: bool = False
+    targets: tuple[McpTarget, ...] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TargetResult:
+    target: McpTarget
+    status: Literal["configured", "already-configured", "skipped", "failed"]
+    detail: str
+
+
+@dataclass(frozen=True, slots=True)
+class SetupResult:
+    vault_status: Literal["configured", "already-configured", "kept"]
+    config: KeepMConfig
+    targets: tuple[TargetResult, ...]
+    instructions: tuple[InstructionResult, ...]
+
+
+def default_language(environment: Mapping[str, str] | None = None) -> MemoryLanguage:
+    values = environment if environment is not None else os.environ
+    locale_name = next(
+        (values[key] for key in ("LC_ALL", "LC_MESSAGES", "LANG") if values.get(key)),
+        "",
+    )
+    return "zh" if locale_name.casefold().startswith("zh") else "en"
+
+
+class SetupCoordinator:
+    def __init__(
+        self,
+        *,
+        store: ConfigStore | None = None,
+        registrar: AgentRegistrar | None = None,
+        prompt: Prompt | None = None,
+        instruction_installer: InstructionInstaller | None = None,
+    ) -> None:
+        self.store = store or ConfigStore()
+        self.registrar = registrar or AgentRegistrar()
+        self.prompt = prompt or TerminalPrompt()
+        registrar_home = getattr(self.registrar, "home", None)
+        self.instruction_installer = instruction_installer or InstructionInstaller(
+            home=registrar_home
+        )
+
+    def run(self, request: SetupRequest) -> SetupResult:
+        config, vault_status = self._configure_vault(request)
+        targets = request.targets
+        if targets is None:
+            targets = self._prompt_targets(request)
+        if targets and not self.registrar.has_uvx():
+            raise SetupError("uvx is required to register KeepM; install uv first")
+
+        results: list[TargetResult] = []
+        instruction_results: list[InstructionResult] = []
+        for target in targets:
+            try:
+                target_result = self.register(target, request=request)
+                results.append(target_result)
+            except IntegrationError as error:
+                results.append(TargetResult(target, "failed", str(error)))
+                continue
+            if target_result.status not in {"configured", "already-configured"}:
+                continue
+            try:
+                instruction_results.append(
+                    self.instruction_installer.install(target, config.language)
+                )
+            except InstructionError as error:
+                instruction_results.append(
+                    InstructionResult(target, None, "failed", str(error))
+                )
+        return SetupResult(
+            vault_status=vault_status,
+            config=config,
+            targets=tuple(results),
+            instructions=tuple(instruction_results),
+        )
+
+    def register(self, target: McpTarget, *, request: SetupRequest) -> TargetResult:
+        if target.scope == "project":
+            assert target.project_dir is not None
+            if not target.project_dir.is_dir():
+                raise SetupError(f"project directory does not exist: {target.project_dir}")
+        state = self.registrar.inspect(target)
+        if state.kind == "equivalent":
+            return TargetResult(target, "already-configured", state.detail)
+        if state.kind == "different":
+            if request.force:
+                self.registrar.apply(target, replace=True)
+                return TargetResult(target, "configured", "replaced existing keepm MCP")
+            if request.assume_yes:
+                raise SetupError(
+                    f"{target.agent} {target.scope} has a different keepm MCP; rerun with --force to replace it"
+                )
+            decision = self.prompt.choose(
+                f"{target.agent} {target.scope} already has a different keepm MCP",
+                ("replace", "skip", "cancel"),
+                default="skip",
+            )
+            if decision == "cancel":
+                raise SetupError("setup cancelled; no remaining MCP registrations were changed")
+            if decision == "skip":
+                return TargetResult(target, "skipped", state.detail)
+            self.registrar.apply(target, replace=True)
+            return TargetResult(target, "configured", "replaced existing keepm MCP")
+
+        self.registrar.apply(target, replace=False)
+        return TargetResult(target, "configured", "registered KeepM MCP")
+
+    def _configure_vault(
+        self, request: SetupRequest
+    ) -> tuple[KeepMConfig, Literal["configured", "already-configured", "kept"]]:
+        existing = self.store.load_optional()
+        vault_path = request.vault_path
+        if vault_path is None and existing is not None:
+            vault_path = existing.vault_path
+        if vault_path is None:
+            if request.assume_yes:
+                raise SetupError("--vault is required with --yes for first-time setup")
+            vault_path = Path(self.prompt.ask("Obsidian Vault path")).expanduser()
+        memory_dir = request.memory_dir or (
+            existing.memory_dir if existing is not None else "Memory"
+        )
+        selected_language = request.language
+        if selected_language is None:
+            language_default = existing.language if existing is not None else default_language()
+            if request.assume_yes:
+                selected_language = language_default
+            else:
+                selected_language = cast(
+                    MemoryLanguage,
+                    self.prompt.choose(
+                        "Memory language", ("zh", "en"), default=language_default
+                    ),
+                )
+        vault_path = vault_path.expanduser().resolve()
+        if not vault_path.is_dir():
+            raise SetupError(f"vault path must be an existing directory: {vault_path}")
+        try:
+            desired = KeepMConfig(
+                vault_path=vault_path,
+                memory_dir=memory_dir,
+                stale_after_seconds=(
+                    existing.stale_after_seconds if existing is not None else 30
+                ),
+                language=selected_language,
+            )
+        except ValueError as error:
+            raise SetupError(str(error)) from error
+
+        if existing == desired:
+            return existing, "already-configured"
+        if existing is not None:
+            same_storage = (
+                existing.vault_path == desired.vault_path
+                and existing.memory_dir == desired.memory_dir
+                and existing.stale_after_seconds == desired.stale_after_seconds
+            )
+            if same_storage:
+                return self.store.save(desired), "configured"
+            if request.force:
+                return self.store.save(desired), "configured"
+            if request.assume_yes:
+                raise SetupError(
+                    "KeepM already uses a different Vault configuration; rerun with --force to replace it"
+                )
+            decision = self.prompt.choose(
+                "KeepM already has a different Vault configuration",
+                ("replace", "keep", "cancel"),
+                default="keep",
+            )
+            if decision == "cancel":
+                raise SetupError("setup cancelled before changing the KeepM Vault")
+            if decision == "keep":
+                return existing, "kept"
+        return self.store.save(desired), "configured"
+
+    def _prompt_targets(self, request: SetupRequest) -> tuple[McpTarget, ...]:
+        agents = self.registrar.available_agents()
+        if not agents:
+            return ()
+        if request.agent is not None:
+            if request.agent not in agents:
+                raise SetupError(f"{request.agent} is not available on PATH")
+            agent = request.agent
+        elif request.assume_yes:
+            if len(agents) != 1:
+                raise SetupError(
+                    "--agent is required with --yes when multiple Agents are available"
+                )
+            agent = agents[0]
+        else:
+            agent = cast(
+                AgentName,
+                self.prompt.choose(
+                    "Agent to register",
+                    agents,
+                    default=agents[0],
+                ),
+            )
+
+        scope = request.scope or "user"
+        if request.scope is None and not request.assume_yes:
+            scope = cast(
+                McpScope,
+                self.prompt.choose(
+                    f"Register KeepM for {agent}",
+                    ("user", "project"),
+                    default="user",
+                ),
+            )
+        return (
+            McpTarget(
+                agent,
+                scope,
+                request.project_dir if scope == "project" else None,
+            ),
+        )
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="keepm setup", description="Configure KeepM and register its local MCP."
+    )
+    parser.add_argument("--vault", type=Path, help="existing local Obsidian Vault path")
+    parser.add_argument(
+        "--memory-dir", help="relative directory inside the Vault (default: Memory)"
+    )
+    parser.add_argument(
+        "--language", choices=("zh", "en"), help="language for Agent instructions and new memories"
+    )
+    parser.add_argument(
+        "--agent", choices=("codex", "claude"), help="Agent to register"
+    )
+    parser.add_argument(
+        "--scope", choices=("user", "project"), help="MCP and instruction scope (default: user)"
+    )
+    parser.add_argument(
+        "--project-dir", type=Path, default=Path.cwd(), help="project for project-scope registration"
+    )
+    parser.add_argument("--yes", action="store_true", help="accept normal confirmations")
+    parser.add_argument(
+        "--force", action="store_true", help="replace a different KeepM configuration without prompting"
+    )
+    return parser
+
+
+def _print_result(result: SetupResult) -> None:
+    print(
+        f"KeepM Vault: {result.vault_status} ({result.config.vault_path}, language={result.config.language})"
+    )
+    for target in result.targets:
+        detail = f" - {target.detail}" if target.status == "failed" else ""
+        print(
+            f"{target.target.agent} ({target.target.scope}): {target.status}{detail}"
+        )
+    for instruction in result.instructions:
+        location = f" ({instruction.path})" if instruction.path is not None else ""
+        detail = f" - {instruction.detail}" if instruction.status == "failed" else ""
+        print(
+            f"{instruction.target.agent} instructions ({instruction.target.scope}): "
+            f"{instruction.status}{location}{detail}"
+        )
+    if not result.targets:
+        print("No supported Agent was selected; register KeepM later with `keepm setup`.")
+        print("Manual registration: codex mcp add keepm -- uvx --from keepm keepm")
+        print(
+            "Manual registration: claude mcp add --scope user keepm -- uvx --from keepm keepm"
+        )
+    print("Restart or open a new Agent session before using the KeepM MCP.")
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = _parser()
+    arguments = parser.parse_args(argv)
+    if not arguments.yes and not sys.stdin.isatty():
+        parser.error("interactive setup requires a TTY; use --yes for automation")
+    request = SetupRequest(
+        vault_path=arguments.vault,
+        memory_dir=arguments.memory_dir,
+        language=cast(MemoryLanguage | None, arguments.language),
+        agent=cast(AgentName | None, arguments.agent),
+        scope=cast(McpScope | None, arguments.scope),
+        project_dir=arguments.project_dir.expanduser().resolve(),
+        force=arguments.force,
+        assume_yes=arguments.yes,
+    )
+    try:
+        result = SetupCoordinator().run(request)
+    except (SetupError, IntegrationError) as error:
+        parser.error(str(error))
+    _print_result(result)