@luisarg/memory-auto 0.1.0 → 0.1.2

package/server/registry.py

@@ -0,0 +1,141 @@
+"""Type registry loader — reads memory/type-registry.yaml and provides
+derived maps for store, server, and digest_session modules.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+
+class RegistryValidationError(Exception):
+    """Raised when the type registry fails validation."""
+
+
+_REQUIRED_KEYS = ("name", "directory", "singular", "tool", "template", "extraction_hint")
+_RESERVED_DIRECTORIES = {"index.md", "log.md", ".obsidian"}
+
+
+def _validate_registry(types: list[dict[str, Any]]) -> None:
+    """Validate a parsed registry. Raises RegistryValidationError on failure."""
+    # Required keys
+    for t in types:
+        for key in _REQUIRED_KEYS:
+            if key not in t:
+                raise RegistryValidationError(
+                    f"missing required key {key!r} in type {t.get('name', '<unnamed>')}"
+                )
+
+    # Duplicate name
+    seen_names: set[str] = set()
+    for t in types:
+        n: str = t["name"]
+        if n in seen_names:
+            raise RegistryValidationError(f"duplicate name: {n!r}")
+        seen_names.add(n)
+
+    # Duplicate directory across project-attached types
+    seen_project_dirs: set[str] = set()
+    for t in types:
+        if t.get("project_attached", True) is True:
+            d: str = t["directory"]
+            if d in seen_project_dirs:
+                raise RegistryValidationError(
+                    f"duplicate directory for project-attached types: {d!r}"
+                )
+            seen_project_dirs.add(d)
+
+    # Reserved directory collision
+    for t in types:
+        d = t.get("directory", "")
+        if d in _RESERVED_DIRECTORIES:
+            raise RegistryValidationError(
+                f"directory {d!r} collides with reserved path"
+            )
+
+    # Empty extraction_hint on project-attached types
+    for t in types:
+        if t.get("project_attached", True) is True:
+            hint = t.get("extraction_hint")
+            if hint is None or (isinstance(hint, str) and hint == ""):
+                raise RegistryValidationError(
+                    f"empty extraction_hint on project-attached type {t.get('name')!r}"
+                )
+
+
+@lru_cache(maxsize=1)
+def load_type_registry(bundle_root: Path) -> list[dict[str, Any]]:
+    """Load and validate the type registry from bundle_root/type-registry.yaml.
+
+    Returns the list of type dicts. Raises RegistryValidationError on
+    validation failure. Uses @lru_cache so the file is read only once.
+    """
+    import yaml  # lazy import: only needed when loading the registry
+
+    registry_path = bundle_root / "type-registry.yaml"
+    if not registry_path.is_file():
+        raise RegistryValidationError(
+            f"registry file not found: {registry_path}"
+        )
+
+    raw = registry_path.read_text(encoding="utf-8")
+    try:
+        data = yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        raise RegistryValidationError(f"YAML parse error: {exc}") from exc
+
+    if not isinstance(data, dict) or "types" not in data:
+        raise RegistryValidationError(
+            "registry must contain a top-level 'types' key"
+        )
+
+    types = data["types"]
+    if not isinstance(types, list) or len(types) == 0:
+        raise RegistryValidationError("'types' must be a non-empty list")
+
+    _validate_registry(types)
+    return types
+
+
+def build_type_maps(
+    types: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Derive the standard maps from a registry type list.
+
+    Returns a dict with keys:
+        valid_types: set of singular names
+        type_dir_map: singular -> directory
+        type_label_map: directory -> name (label)
+        dir_to_singular: directory -> singular
+        type_order: list of directory names in registry order (project-attached only)
+        extraction_types: list of dicts for types with non-null extraction_hint
+    """
+    valid_types: set[str] = set()
+    type_dir_map: dict[str, str] = {}
+    type_label_map: dict[str, str] = {}
+    dir_to_singular: dict[str, str] = {}
+    type_order: list[str] = []
+    extraction_types: list[dict[str, Any]] = []
+
+    for t in types:
+        singular = t["singular"]
+        directory = t["directory"]
+        name = t["name"]
+        valid_types.add(singular)
+        type_dir_map[singular] = directory
+        type_label_map[directory] = name
+        dir_to_singular[directory] = singular
+        if t.get("project_attached", True):
+            type_order.append(directory)
+        if t.get("extraction_hint") is not None:
+            extraction_types.append(t)
+
+    return {
+        "valid_types": valid_types,
+        "type_dir_map": type_dir_map,
+        "type_label_map": type_label_map,
+        "dir_to_singular": dir_to_singular,
+        "type_order": type_order,
+        "extraction_types": extraction_types,
+    }

package/server/requirements.txt

@@ -0,0 +1,4 @@
+# Mirror of the dependencies in pyproject.toml — keep in sync by hand.
+# Used only by launcher.mjs' pip fallback on hosts without uv.
+mcp>=1.2.0
+PyYAML>=6.0

package/server/server.py

@@ -0,0 +1,399 @@
+"""MCP server exposing memory store tools via the Model Context Protocol.
+
+Eight tools (per openspec/specs/memory-mcp-server/spec.md):
+    search_memory, store_decision, store_fact, store_learning,
+    store_convention, store_profile, export_memories, get_profile, ping.
+
+All reads are explicit (no background polling). Server validates storage
+accessibility at startup.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.lowlevel.server import ServerRequestContext
+from mcp.server.stdio import stdio_server
+from mcp.types import (
+    CallToolRequestParams,
+    CallToolResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    TextContent,
+    Tool,
+)
+
+from store import (
+    VALID_TYPES,
+    MemoryStore,
+    _first_non_heading_line,
+)
+
+# Observability log: append-only JSONL. Path is derived from MEMORY_PATH so the
+# log lives next to the bundle, never blocking tool behavior.
+_LOG_PATH: Path | None = None
+
+
+def _log_path() -> Path:
+    global _LOG_PATH
+    if _LOG_PATH is not None:
+        return _LOG_PATH
+    from cli import get_memory_path
+
+    base = get_memory_path()
+    _LOG_PATH = base / "tool-calls.log"
+    return _LOG_PATH
+
+
+def _log_tool_call(tool_name: str, params: dict) -> None:
+    """Append a JSONL entry for each tool call. Silently ignore write errors."""
+    try:
+        entry = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "tool": tool_name,
+            "project": params.get("project"),
+            "entry_type": params.get("entry_type"),
+        }
+        path = _log_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "a") as f:
+            f.write(json.dumps(entry, default=str) + "\n")
+    except Exception:
+        pass
+
+
+def _require(params: dict, key: str) -> str:
+    val = params.get(key)
+    if not val:
+        raise ValueError(f"'{key}' is required and must not be empty")
+    return val
+
+
+def _derive_description(content: str) -> str:
+    """Derive a one-sentence description from the first non-heading line."""
+    return _first_non_heading_line(content) or content[:120]
+
+
+# ── Tool handlers (sync, return JSON strings) ──────────────────────────────
+
+
+def handle_search_memory(store: MemoryStore, params: dict) -> str:
+    project = params.get("project") or None
+    entry_type = params.get("entry_type") or None
+    tags = params.get("tags") or None
+    query = params.get("query") or None
+    results = store.search_entries(
+        project=project, entry_type=entry_type, tags=tags, query=query
+    )
+    return json.dumps(results)
+
+
+def _handle_store_typed(
+    store: MemoryStore, params: dict, entry_type: str
+) -> str:
+    project = _require(params, "project")
+    content = _require(params, "content")
+    tags = params.get("tags") or []
+    description = params.get("description")
+    if not description or not str(description).strip():
+        description = _derive_description(content)
+    openspec_change_id = params.get("openspec_change_id") or None
+    confidence = params.get("confidence", 1.0)
+    if confidence is None:
+        confidence = 1.0
+    entry = store.upsert_entry(
+        entry_type=entry_type,
+        project=project,
+        content=content,
+        tags=tags,
+        description=str(description).strip(),
+        confidence=float(confidence),
+        openspec_change_id=openspec_change_id,
+    )
+    return json.dumps(entry)
+
+
+def handle_store_decision(store: MemoryStore, params: dict) -> str:
+    return _handle_store_typed(store, params, "decision")
+
+
+def handle_store_fact(store: MemoryStore, params: dict) -> str:
+    return _handle_store_typed(store, params, "fact")
+
+
+def handle_store_learning(store: MemoryStore, params: dict) -> str:
+    return _handle_store_typed(store, params, "learning")
+
+
+def handle_store_convention(store: MemoryStore, params: dict) -> str:
+    return _handle_store_typed(store, params, "convention")
+
+
+def handle_store_profile(store: MemoryStore, params: dict) -> str:
+    project = _require(params, "project")
+    content = _require(params, "content")
+    tags = params.get("tags") or []
+    entry = store.upsert_profile(project=project, content=content, tags=tags)
+    return json.dumps(entry)
+
+
+def handle_export_memories(store: MemoryStore, params: dict) -> str:
+    project = _require(params, "project")
+    entry_type = params.get("entry_type") or None
+    results = store.export_entries(project=project, entry_type=entry_type)
+    return json.dumps(results)
+
+
+def handle_get_profile(store: MemoryStore, params: dict) -> str:
+    project = _require(params, "project")
+    entry_type = params.get("entry_type") or None
+    results = store.get_profile(project=project, entry_type=entry_type)
+    return json.dumps(results)
+
+
+def handle_ping(store: MemoryStore, params: dict) -> str:
+    return json.dumps(
+        {"status": "ok", "timestamp": datetime.now(timezone.utc).isoformat()}
+    )
+
+
+def handle_store_source(store: MemoryStore, params: dict) -> str:
+    url = _require(params, "url")
+    title = _require(params, "title")
+    description = _require(params, "description")
+    source_kind = _require(params, "source_kind")
+    tags = params.get("tags") or []
+    content = params.get("content") or None
+    supersedes = params.get("supersedes") or None
+    result = store.store_source(
+        url=url,
+        title=title,
+        description=description,
+        source_kind=source_kind,
+        tags=tags,
+        content=content,
+        supersedes=supersedes,
+    )
+    return json.dumps(result)
+
+
+# ── Tool definitions (shared between list_tools and the wire-up) ──────────
+
+
+def _tool_definitions() -> list[Tool]:
+    """Static tool definitions for the memory-server MCP surface."""
+    valid_types = sorted(VALID_TYPES)
+    return [
+        Tool(
+            name="search_memory",
+            description="Search memory entries across projects. Omit project to search all projects.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "project": {"type": "string"},
+                    "entry_type": {"type": "string", "enum": valid_types},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                    "query": {"type": "string"},
+                },
+            },
+        ),
+        Tool(
+            name="store_decision",
+            description="Store a decision entry",
+            inputSchema={
+                "type": "object",
+                "required": ["project", "content"],
+                "properties": {
+                    "project": {"type": "string"},
+                    "content": {"type": "string"},
+                    "description": {"type": "string"},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                    "openspec_change_id": {"type": "string"},
+                },
+            },
+        ),
+        Tool(
+            name="store_fact",
+            description="Store a fact entry",
+            inputSchema={
+                "type": "object",
+                "required": ["project", "content"],
+                "properties": {
+                    "project": {"type": "string"},
+                    "content": {"type": "string"},
+                    "description": {"type": "string"},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                    "confidence": {"type": "number", "minimum": 0.0, "maximum": 1.0},
+                },
+            },
+        ),
+        Tool(
+            name="store_learning",
+            description="Store a learning entry",
+            inputSchema={
+                "type": "object",
+                "required": ["project", "content"],
+                "properties": {
+                    "project": {"type": "string"},
+                    "content": {"type": "string"},
+                    "description": {"type": "string"},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                },
+            },
+        ),
+        Tool(
+            name="store_convention",
+            description="Store a convention entry",
+            inputSchema={
+                "type": "object",
+                "required": ["project", "content"],
+                "properties": {
+                    "project": {"type": "string"},
+                    "content": {"type": "string"},
+                    "description": {"type": "string"},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                },
+            },
+        ),
+        Tool(
+            name="store_profile",
+            description="Store or update a user profile entry for a project",
+            inputSchema={
+                "type": "object",
+                "required": ["project", "content"],
+                "properties": {
+                    "project": {"type": "string"},
+                    "content": {"type": "string"},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                },
+            },
+        ),
+        Tool(
+            name="store_source",
+            description="Store a source reference (article, transcript, PDF, video, link)",
+            inputSchema={
+                "type": "object",
+                "required": ["url", "title", "description", "source_kind"],
+                "properties": {
+                    "url": {"type": "string"},
+                    "title": {"type": "string"},
+                    "description": {"type": "string"},
+                    "source_kind": {
+                        "type": "string",
+                        "enum": ["article", "transcript", "pdf", "video", "link", "other"],
+                    },
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                    "content": {"type": "string"},
+                    "supersedes": {"type": "string"},
+                },
+            },
+        ),
+        Tool(
+            name="export_memories",
+            description="Export all memory entries for a project (no limit)",
+            inputSchema={
+                "type": "object",
+                "required": ["project"],
+                "properties": {
+                    "project": {"type": "string"},
+                    "entry_type": {"type": "string", "enum": valid_types},
+                },
+            },
+        ),
+        Tool(
+            name="get_profile",
+            description="Retrieve the global tech profile for a project",
+            inputSchema={
+                "type": "object",
+                "required": ["project"],
+                "properties": {
+                    "project": {"type": "string"},
+                    "entry_type": {"type": "string", "enum": valid_types},
+                },
+            },
+        ),
+        Tool(
+            name="ping",
+            description="Health check — returns ok and current timestamp",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+    ]
+
+
+# ── MCP server factory (mcp 1.26.0 keyword-arg API) ───────────────────────
+
+
+def create_app(store: MemoryStore) -> Server:
+    """Create and return a configured MCP server instance.
+
+    Uses the keyword-argument API of `mcp.server.Server` (>= 1.0). The handlers
+    run synchronously (the underlying MCP layer awaits them in an executor).
+    """
+    tool_defs = _tool_definitions()
+    handlers = {
+        "search_memory": handle_search_memory,
+        "store_decision": handle_store_decision,
+        "store_fact": handle_store_fact,
+        "store_learning": handle_store_learning,
+        "store_convention": handle_store_convention,
+        "store_profile": handle_store_profile,
+        "store_source": handle_store_source,
+        "export_memories": handle_export_memories,
+        "get_profile": handle_get_profile,
+        "ping": handle_ping,
+    }
+
+    async def on_list_tools(
+        ctx: ServerRequestContext, params: PaginatedRequestParams | None
+    ) -> ListToolsResult:
+        return ListToolsResult(tools=tool_defs)
+
+    async def on_call_tool(
+        ctx: ServerRequestContext, params: CallToolRequestParams
+    ) -> CallToolResult:
+        name = params.name
+        arguments: dict[str, Any] = dict(params.arguments or {})
+        if name not in handlers:
+            raise ValueError(f"Unknown tool: {name}")
+        text = handlers[name](store, arguments)
+        _log_tool_call(name, arguments)
+        return CallToolResult(
+            content=[TextContent(type="text", text=text)],
+            isError=False,
+        )
+
+    return Server(
+        "memory-server",
+        on_list_tools=on_list_tools,
+        on_call_tool=on_call_tool,
+    )
+
+
+# ── Entry point for `memory-server` console script ──────────────────────────
+
+
+async def run() -> None:
+    """Validate storage, build store, start stdio MCP server."""
+    from cli import get_memory_path, validate_storage_path
+
+    memory_path = get_memory_path()
+    validate_storage_path(str(memory_path))
+    store = MemoryStore(storage_path=memory_path)
+    store.initialize()
+    app = create_app(store)
+    async with stdio_server() as (r, w):
+        await app.run(r, w, app.create_initialization_options())
+
+
+def main() -> None:
+    import asyncio
+
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()