opencode-semantic-memory 0.1.0__py3-none-any.whl

opencode_memory/server.py

@@ -0,0 +1,2795 @@
+"""MCP server for opencode-memory."""
+
+import asyncio
+import logging
+import os
+import re
+import subprocess
+import time
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from opencode_memory.cache import MemoryCache
+from opencode_memory.config import Config
+from opencode_memory.daemon import IngestionDaemon
+from opencode_memory.enrichment.gitlab import GitLabEnricher
+from opencode_memory.ingestion.embeddings import EmbeddingEngine
+from opencode_memory.ingestion.parser import MarkdownParser
+from opencode_memory.models import (
+    BootContext,
+    Entity,
+    EntityType,
+    LinkType,
+    Memory,
+    MemoryCategory,
+    MemoryLink,
+)
+from opencode_memory.query.hybrid import HybridSearchEngine
+from opencode_memory.session.registry import SessionRegistry
+from opencode_memory.storage.sqlite import SQLiteStorage
+from opencode_memory.storage.vectors import VectorStorage
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def _format_age(created_at: datetime) -> str:
+    """Format memory age as human-readable string."""
+    from datetime import timezone as tz
+
+    now = datetime.now(tz.utc)
+    # Handle naive datetimes by assuming UTC
+    if created_at.tzinfo is None:
+        created_at = created_at.replace(tzinfo=tz.utc)
+
+    delta = now - created_at
+    days = delta.days
+
+    if days == 0:
+        hours = delta.seconds // 3600
+        if hours == 0:
+            minutes = delta.seconds // 60
+            return f"{minutes}m" if minutes > 0 else "now"
+        return f"{hours}h"
+    elif days == 1:
+        return "1d"
+    elif days < 7:
+        return f"{days}d"
+    elif days < 30:
+        weeks = days // 7
+        return f"{weeks}w"
+    elif days < 365:
+        months = days // 30
+        return f"{months}mo"
+    else:
+        years = days // 365
+        return f"{years}y"
+
+
+def _detect_current_project() -> str | None:
+    """Detect current project from git remote URL."""
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            cwd=os.getcwd(),
+        )
+        if result.returncode != 0:
+            return None
+
+        url = result.stdout.strip()
+        # Parse git@gitlab.com:group/project.git or https://gitlab.com/group/project.git
+        match = re.search(r"(?:git@[^:]+:|https?://[^/]+/)(.+?)(?:\.git)?$", url)
+        if match:
+            return match.group(1)
+    except Exception:
+        pass
+    return None
+
+
+MAX_PENDING_EMBEDDINGS = 100  # Max queued embeddings before blocking
+CACHE_CLEANUP_INTERVAL_SECONDS = 60  # Clean expired cache entries every minute
+
+
+class BackgroundTaskRegistry:
+    """Track running background tasks for status reporting."""
+
+    def __init__(self):
+        self._tasks: dict[str, dict] = {}  # task_id -> {name, started_at, task}
+
+    def register(self, name: str, task: asyncio.Task) -> str:
+        """Register a background task. Returns task_id."""
+        import uuid
+
+        task_id = str(uuid.uuid4())[:8]
+        self._tasks[task_id] = {
+            "name": name,
+            "started_at": time.time(),
+            "task": task,
+        }
+
+        # Auto-cleanup when task completes
+        def cleanup(t):
+            self._tasks.pop(task_id, None)
+
+        task.add_done_callback(cleanup)
+        return task_id
+
+    def get_running_tasks(self) -> list[dict]:
+        """Get list of currently running tasks."""
+        now = time.time()
+        result = []
+        for task_id, info in list(self._tasks.items()):
+            if not info["task"].done():
+                result.append(
+                    {
+                        "id": task_id,
+                        "name": info["name"],
+                        "running_seconds": int(now - info["started_at"]),
+                    }
+                )
+        return result
+
+    def is_task_running(self, name: str) -> bool:
+        """Check if a task with given name is running."""
+        return any(
+            info["name"] == name and not info["task"].done() for info in self._tasks.values()
+        )
+
+
+_background_tasks = BackgroundTaskRegistry()
+
+
+class MemoryServer:
+    """MCP server providing memory tools."""
+
+    # Limit concurrent background embedding tasks to prevent resource exhaustion
+    _embedding_semaphore: asyncio.Semaphore | None = None
+    _pending_embeddings: set[asyncio.Task] = set()
+
+    @classmethod
+    async def wait_for_pending_embeddings(cls, timeout: float = 5.0) -> int:
+        """Wait for pending background embedding tasks to complete.
+
+        Args:
+            timeout: Maximum seconds to wait (default 5)
+
+        Returns:
+            Number of tasks that were still pending (0 = all completed)
+        """
+        if not cls._pending_embeddings:
+            return 0
+
+        pending = list(cls._pending_embeddings)
+        if not pending:
+            return 0
+
+        done, still_pending = await asyncio.wait(pending, timeout=timeout)
+        return len(still_pending)
+
+    def __init__(self, config: Config | None = None, enable_daemon: bool = True):
+        self.config = config or Config.load()
+        self.config.storage_path.mkdir(parents=True, exist_ok=True)
+
+        self.sqlite = SQLiteStorage(self.config.db_path)
+        self.embeddings = EmbeddingEngine()
+        self.vectors = VectorStorage(self.config.vectors_path, self.embeddings.dimension)
+        self.search_engine = HybridSearchEngine(self.sqlite, self.vectors, self.embeddings)
+        self.session_registry = SessionRegistry(self.sqlite)
+        self.parser = MarkdownParser()
+        self.memory_cache = MemoryCache(self.sqlite)  # Uses defaults: 50k entries, 24h TTL
+        self._cache_cleanup_task: asyncio.Task | None = None
+
+        # Initialize semaphore (max 4 concurrent embeddings)
+        if MemoryServer._embedding_semaphore is None:
+            MemoryServer._embedding_semaphore = asyncio.Semaphore(4)
+
+        self._enable_daemon = enable_daemon
+        self.daemon: IngestionDaemon | None = None
+        if enable_daemon:
+            self.daemon = IngestionDaemon(self.config, self.sqlite, self.vectors, self.embeddings)
+
+        self.enricher = GitLabEnricher()
+
+        self.server = Server("opencode-memory")
+        self._register_tools()
+
+    def _register_tools(self) -> None:
+        """Register MCP tools."""
+
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            return [
+                Tool(
+                    name="recall",
+                    description=(
+                        "Search long-term memory semantically. Use this to find relevant context "
+                        "before working on any task. Examples: 'database migration guidelines', "
+                        "'how to write GitLab comments', 'MR review process', 'known blockers'. "
+                        "Combines semantic search with full-text search for best results."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "query": {
+                                "type": "string",
+                                "description": "Natural language search query",
+                            },
+                            "limit": {
+                                "type": "integer",
+                                "description": "Max results (default 10)",
+                                "default": 10,
+                            },
+                            "project": {
+                                "type": "string",
+                                "description": "Filter by project (e.g. 'gitlab-org/gitlab'). Use 'auto' to detect from git remote. If not provided, searches all projects.",
+                            },
+                            "compact": {
+                                "type": "boolean",
+                                "description": "Return compact results (truncated content, no source) to reduce token usage. Default false.",
+                                "default": False,
+                            },
+                            "since_days": {
+                                "type": "integer",
+                                "description": "Only search memories from the last N days",
+                            },
+                            "category": {
+                                "type": "string",
+                                "enum": [
+                                    "decision",
+                                    "blocker",
+                                    "procedure",
+                                    "fact",
+                                    "event",
+                                    "conversation",
+                                    "directive",
+                                    "plan",
+                                    "idea",
+                                ],
+                                "description": "Filter by memory category",
+                            },
+                        },
+                        "required": ["query"],
+                    },
+                ),
+                Tool(
+                    name="remember",
+                    description=(
+                        "Store an important memory for future sessions. Use this for: "
+                        "decisions made (why we chose approach X), blockers discovered "
+                        "(what's blocking MR !123), procedures learned (how to do X), "
+                        "or facts worth preserving. Memories persist across all sessions."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "content": {
+                                "type": "string",
+                                "description": "The memory content - be specific and include context",
+                            },
+                            "category": {
+                                "type": "string",
+                                "enum": [
+                                    "decision",
+                                    "blocker",
+                                    "procedure",
+                                    "fact",
+                                    "event",
+                                    "directive",
+                                    "plan",
+                                    "idea",
+                                ],
+                                "description": (
+                                    "decision: architectural/design choices; "
+                                    "blocker: obstacles preventing progress; "
+                                    "procedure: how-to knowledge; "
+                                    "fact: project-specific information; "
+                                    "event: significant occurrences; "
+                                    "directive: always-on instructions for every session; "
+                                    "plan: long-term goals and strategies to achieve them; "
+                                    "idea: future possibilities, deferred considerations, things to try later"
+                                ),
+                            },
+                            "entities": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "Related entities: !123 (MR), #456 (issue), &789 (epic), @user",
+                            },
+                            "what": {
+                                "type": "string",
+                                "description": "Brief summary of what happened",
+                            },
+                            "why": {
+                                "type": "string",
+                                "description": "Why this matters or why the decision was made",
+                            },
+                            "learned": {
+                                "type": "string",
+                                "description": "Key takeaway or lesson for future reference",
+                            },
+                            "project": {
+                                "type": "string",
+                                "description": "Project context (e.g. 'gitlab-org/gitlab'). Auto-detected if not provided.",
+                            },
+                        },
+                        "required": ["content", "category"],
+                    },
+                ),
+                Tool(
+                    name="get_context",
+                    description=(
+                        "Get all stored memories related to an entity. ALWAYS call this before "
+                        "working on an MR, issue, or epic to understand history, prior decisions, "
+                        "and known blockers. Returns memories tagged with the entity."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "entity_ref": {
+                                "type": "string",
+                                "description": "Entity reference: !123 (MR), #456 (issue), &789 (epic), @user",
+                            },
+                        },
+                        "required": ["entity_ref"],
+                    },
+                ),
+                Tool(
+                    name="get_active_sessions",
+                    description=(
+                        "List other active OpenCode sessions and what they're working on. "
+                        "Check this before claiming items to avoid conflicts with parallel sessions."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {},
+                    },
+                ),
+                Tool(
+                    name="session_start",
+                    description=(
+                        "Register this session at startup. Enables session coordination, "
+                        "item claiming, and activity tracking across parallel OpenCode instances."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "session_id": {
+                                "type": "string",
+                                "description": "Unique session identifier (e.g., 'mr-review-225172')",
+                            },
+                            "working_on": {
+                                "type": "string",
+                                "description": "Brief description of the task",
+                            },
+                        },
+                        "required": ["session_id"],
+                    },
+                ),
+                Tool(
+                    name="session_heartbeat",
+                    description="Update session heartbeat. Call periodically during long tasks.",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "session_id": {
+                                "type": "string",
+                                "description": "Session identifier",
+                            },
+                        },
+                        "required": ["session_id"],
+                    },
+                ),
+                Tool(
+                    name="session_end",
+                    description=(
+                        "End a session. Provide a summary to persist key accomplishments "
+                        "and decisions for future sessions to recall."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "session_id": {
+                                "type": "string",
+                                "description": "Session identifier",
+                            },
+                            "summary": {
+                                "type": "string",
+                                "description": "Summary of accomplishments and key decisions",
+                            },
+                        },
+                        "required": ["session_id"],
+                    },
+                ),
+                Tool(
+                    name="claim_item",
+                    description=(
+                        "Claim exclusive ownership of an item (MR, issue, epic) to prevent "
+                        "other sessions from working on it simultaneously. ALWAYS claim before "
+                        "making changes. Returns current owner if already claimed."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "session_id": {
+                                "type": "string",
+                                "description": "Your session identifier",
+                            },
+                            "item_ref": {
+                                "type": "string",
+                                "description": "Item to claim: !123 (MR), #456 (issue), &789 (epic)",
+                            },
+                        },
+                        "required": ["session_id", "item_ref"],
+                    },
+                ),
+                Tool(
+                    name="release_item",
+                    description=(
+                        "Release a claimed item so other sessions can work on it. "
+                        "Call this when done working on an item."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "session_id": {
+                                "type": "string",
+                                "description": "Your session identifier",
+                            },
+                            "item_ref": {
+                                "type": "string",
+                                "description": "Item to release",
+                            },
+                        },
+                        "required": ["session_id", "item_ref"],
+                    },
+                ),
+                Tool(
+                    name="get_boot_context",
+                    description=(
+                        "Get startup context for a new session. Returns: user identity, "
+                        "active parallel sessions, unresolved blockers, and recent decisions. "
+                        "Call this at the start of every session for situational awareness."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {},
+                    },
+                ),
+                Tool(
+                    name="search_history",
+                    description=(
+                        "Search past decisions, blockers, and events with optional category filter. "
+                        "Use for targeted searches like 'all blockers related to migrations' or "
+                        "'decisions about API design'."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "query": {
+                                "type": "string",
+                                "description": "Search query",
+                            },
+                            "category": {
+                                "type": "string",
+                                "enum": [
+                                    "decision",
+                                    "blocker",
+                                    "procedure",
+                                    "fact",
+                                    "event",
+                                    "conversation",
+                                    "directive",
+                                    "plan",
+                                    "idea",
+                                ],
+                                "description": "Filter by memory category",
+                            },
+                            "limit": {
+                                "type": "integer",
+                                "default": 20,
+                            },
+                        },
+                        "required": ["query"],
+                    },
+                ),
+                Tool(
+                    name="ingest_file",
+                    description=(
+                        "Manually ingest a markdown file into memory. Use for importing "
+                        "guidelines, notes, or documentation that should be searchable."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "file_path": {
+                                "type": "string",
+                                "description": "Absolute path to the file to ingest",
+                            },
+                        },
+                        "required": ["file_path"],
+                    },
+                ),
+                Tool(
+                    name="enrich_entity",
+                    description=(
+                        "Fetch metadata for an entity (MR, issue, epic, user) from GitLab API. "
+                        "Updates the entity with title, state, labels, and other metadata. "
+                        "Useful when you want current information about an entity."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "entity_ref": {
+                                "type": "string",
+                                "description": "Entity reference: !123 (MR), #456 (issue), &789 (epic), @user",
+                            },
+                            "project": {
+                                "type": "string",
+                                "description": "Project path (default: gitlab-org/gitlab)",
+                            },
+                        },
+                        "required": ["entity_ref"],
+                    },
+                ),
+                Tool(
+                    name="resolve_blocker",
+                    description=(
+                        "Mark a blocker as resolved. Use when a blocking issue has been fixed "
+                        "or is no longer relevant. Resolved blockers won't appear in boot context."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "memory_id": {
+                                "type": "integer",
+                                "description": "ID of the blocker memory to resolve",
+                            },
+                        },
+                        "required": ["memory_id"],
+                    },
+                ),
+                Tool(
+                    name="unresolve_blocker",
+                    description=(
+                        "Mark a previously resolved blocker as unresolved again. "
+                        "Use if a blocker resurfaces or was resolved prematurely."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "memory_id": {
+                                "type": "integer",
+                                "description": "ID of the blocker memory to unresolve",
+                            },
+                        },
+                        "required": ["memory_id"],
+                    },
+                ),
+                Tool(
+                    name="consolidate_memory",
+                    description=(
+                        "Analyze all memories and identify issues: stale records (old facts that may be outdated), "
+                        "duplicates (similar content), and potential contradictions. Returns a report with "
+                        "recommendations for cleanup. Use periodically to maintain memory quality."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "project": {
+                                "type": "string",
+                                "description": "Filter by project (optional). Use 'auto' to detect from git.",
+                            },
+                            "days_stale": {
+                                "type": "integer",
+                                "description": "Consider records older than this many days as potentially stale (default: 30)",
+                                "default": 30,
+                            },
+                        },
+                    },
+                ),
+                Tool(
+                    name="log_session",
+                    description=(
+                        "Log a session summary with key learnings. Use at the end of significant work sessions "
+                        "to preserve context for future sessions. Automatically extracts and stores insights."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "summary": {
+                                "type": "string",
+                                "description": "Brief summary of what was accomplished",
+                            },
+                            "learnings": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "Key learnings or insights from the session",
+                            },
+                            "entities": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "Related entities (!MR, #issue, &epic)",
+                            },
+                            "project": {
+                                "type": "string",
+                                "description": "Project context (auto-detected if not provided)",
+                            },
+                        },
+                        "required": ["summary"],
+                    },
+                ),
+                Tool(
+                    name="archive_memory",
+                    description=(
+                        "Archive an outdated memory record. Archived records are preserved for history "
+                        "but won't appear in regular searches. Use for facts that are no longer true "
+                        "or decisions that have been superseded."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "memory_id": {
+                                "type": "integer",
+                                "description": "ID of the memory to archive",
+                            },
+                            "reason": {
+                                "type": "string",
+                                "description": "Why this memory is being archived (e.g., 'superseded by new decision')",
+                            },
+                        },
+                        "required": ["memory_id"],
+                    },
+                ),
+                Tool(
+                    name="bootstrap_memory",
+                    description=(
+                        "Bootstrap project memory by scanning common project files (README, package.json, "
+                        "Gemfile, etc.) and extracting basic facts. Run this once when starting work on "
+                        "a new project to build initial knowledge base. Safe to run multiple times - "
+                        "won't duplicate existing facts."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "path": {
+                                "type": "string",
+                                "description": "Project root path (defaults to current directory)",
+                            },
+                        },
+                    },
+                ),
+                Tool(
+                    name="memory_status",
+                    description=(
+                        "Get memory system status including pending embedding queue, storage stats, "
+                        "and daemon health. Use this to check if the system is keeping up with ingestion."
+                    ),
+                    inputSchema={"type": "object", "properties": {}},
+                ),
+                Tool(
+                    name="get_linked_memories",
+                    description=(
+                        "Get memories linked to a specific memory. Use this to explore related context "
+                        "when a search result has linked_memories hints. Returns full content of linked "
+                        "memories with link type and reason."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "memory_id": {
+                                "type": "integer",
+                                "description": "ID of the memory to get links for",
+                            },
+                            "link_types": {
+                                "type": "array",
+                                "items": {
+                                    "type": "string",
+                                    "enum": [
+                                        "related",
+                                        "extends",
+                                        "supersedes",
+                                        "contradicts",
+                                        "same_entity",
+                                    ],
+                                },
+                                "description": "Filter by link types (optional, returns all if not specified)",
+                            },
+                        },
+                        "required": ["memory_id"],
+                    },
+                ),
+                Tool(
+                    name="export_memories",
+                    description=(
+                        "Export memories to a JSON file for backup or transfer. "
+                        "Can filter by project, category, or date range. "
+                        "Returns the path to the exported file."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "output_path": {
+                                "type": "string",
+                                "description": "Path to write the export file (default: ~/opencode-memory-export.json)",
+                            },
+                            "project": {
+                                "type": "string",
+                                "description": "Filter by project (use 'auto' for current project)",
+                            },
+                            "categories": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "Filter by categories (e.g., ['decision', 'procedure'])",
+                            },
+                            "since_days": {
+                                "type": "integer",
+                                "description": "Only export memories from the last N days",
+                            },
+                            "include_archived": {
+                                "type": "boolean",
+                                "description": "Include archived memories (default: false)",
+                            },
+                        },
+                    },
+                ),
+                Tool(
+                    name="import_memories",
+                    description=(
+                        "Import memories from a JSON export file. "
+                        "Use 'dry_run' to preview what will be imported without making changes. "
+                        "Skips duplicates based on content similarity."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "input_path": {
+                                "type": "string",
+                                "description": "Path to the export file to import",
+                            },
+                            "dry_run": {
+                                "type": "boolean",
+                                "description": "Preview import without making changes (default: false)",
+                            },
+                            "skip_duplicates": {
+                                "type": "boolean",
+                                "description": "Skip memories that match existing content (default: true)",
+                            },
+                        },
+                        "required": ["input_path"],
+                    },
+                ),
+                Tool(
+                    name="bulk_archive",
+                    description=(
+                        "Archive multiple memories at once. Use with caution. "
+                        "Can archive by IDs, category, or age. Returns count of archived memories."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "memory_ids": {
+                                "type": "array",
+                                "items": {"type": "integer"},
+                                "description": "List of memory IDs to archive",
+                            },
+                            "category": {
+                                "type": "string",
+                                "description": "Archive all resolved memories in this category",
+                            },
+                            "older_than_days": {
+                                "type": "integer",
+                                "description": "Archive resolved memories older than N days",
+                            },
+                            "reason": {
+                                "type": "string",
+                                "description": "Reason for archiving (required)",
+                            },
+                        },
+                        "required": ["reason"],
+                    },
+                ),
+                Tool(
+                    name="delete_memory",
+                    description=(
+                        "Permanently delete a memory. Use archive_memory for soft delete. "
+                        "This removes the memory from search, FTS index, and all links. Cannot be undone."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "memory_id": {
+                                "type": "integer",
+                                "description": "ID of the memory to delete",
+                            },
+                            "also_delete_vector": {
+                                "type": "boolean",
+                                "description": "Also delete from vector store (default true)",
+                                "default": True,
+                            },
+                        },
+                        "required": ["memory_id"],
+                    },
+                ),
+                Tool(
+                    name="edit_memory",
+                    description=(
+                        "Edit a memory's content or metadata. Only provided fields are updated. "
+                        "Use for correcting mistakes or updating stale information."
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "memory_id": {
+                                "type": "integer",
+                                "description": "ID of the memory to edit",
+                            },
+                            "content": {
+                                "type": "string",
+                                "description": "New content (replaces existing)",
+                            },
+                            "what": {
+                                "type": "string",
+                                "description": "New 'what' summary",
+                            },
+                            "why": {
+                                "type": "string",
+                                "description": "New 'why' explanation",
+                            },
+                            "learned": {
+                                "type": "string",
+                                "description": "New 'learned' takeaway",
+                            },
+                            "recompute_embedding": {
+                                "type": "boolean",
+                                "description": "Recompute vector embedding if content changed (default true)",
+                                "default": True,
+                            },
+                        },
+                        "required": ["memory_id"],
+                    },
+                ),
+            ]
+
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+            try:
+                result = await self._handle_tool(name, arguments)
+                return [TextContent(type="text", text=str(result))]
+            except Exception as e:
+                logger.exception(f"Error handling tool {name}")
+                return [TextContent(type="text", text=f"Error: {e}")]
+
+    async def _handle_tool(self, name: str, args: dict[str, Any]) -> Any:
+        """Handle a tool call using dispatch table."""
+        # Dispatch table maps tool name to (handler, is_async, args_extractor)
+        # Using lambdas for args extraction keeps the mapping clean
+        dispatch = {
+            "recall": (
+                self._recall,
+                True,
+                lambda a: (
+                    a["query"],
+                    a.get("limit", 10),
+                    a.get("project"),
+                    a.get("compact", False),
+                    a.get("since_days"),
+                    a.get("category"),
+                ),
+            ),
+            "remember": (
+                self._remember,
+                True,
+                lambda a: (
+                    a["content"],
+                    a["category"],
+                    a.get("entities", []),
+                    a.get("what"),
+                    a.get("why"),
+                    a.get("learned"),
+                    a.get("project"),
+                ),
+            ),
+            "get_context": (
+                self._get_context,
+                True,  # Now async - includes semantic search
+                lambda a: (a["entity_ref"],),
+            ),
+            "get_active_sessions": (
+                self._get_active_sessions,
+                False,
+                lambda a: (),
+            ),
+            "session_start": (
+                self._session_start,
+                False,
+                lambda a: (a["session_id"], a.get("working_on")),
+            ),
+            "session_heartbeat": (
+                self._session_heartbeat,
+                False,
+                lambda a: (a["session_id"],),
+            ),
+            "session_end": (
+                self._session_end,
+                True,
+                lambda a: (a["session_id"], a.get("summary")),
+            ),
+            "claim_item": (
+                self._claim_item,
+                False,
+                lambda a: (a["session_id"], a["item_ref"]),
+            ),
+            "release_item": (
+                self._release_item,
+                False,
+                lambda a: (a["session_id"], a["item_ref"]),
+            ),
+            "get_boot_context": (
+                self._get_boot_context,
+                False,
+                lambda a: (),
+            ),
+            "search_history": (
+                self._search_history,
+                False,
+                lambda a: (a["query"], a.get("category"), a.get("limit", 20)),
+            ),
+            "ingest_file": (
+                self._ingest_file,
+                True,  # async
+                lambda a: (a["file_path"],),
+            ),
+            "enrich_entity": (
+                self._enrich_entity,
+                True,
+                lambda a: (a["entity_ref"], a.get("project")),
+            ),
+            "resolve_blocker": (
+                self._resolve_blocker,
+                False,
+                lambda a: (a["memory_id"],),
+            ),
+            "unresolve_blocker": (
+                self._unresolve_blocker,
+                False,
+                lambda a: (a["memory_id"],),
+            ),
+            "consolidate_memory": (
+                self._consolidate_memory,
+                False,
+                lambda a: (a.get("project"), a.get("days_stale", 30)),
+            ),
+            "log_session": (
+                self._log_session,
+                True,
+                lambda a: (
+                    a["summary"],
+                    a.get("learnings", []),
+                    a.get("entities", []),
+                    a.get("project"),
+                ),
+            ),
+            "archive_memory": (
+                self._archive_memory,
+                False,
+                lambda a: (a["memory_id"], a.get("reason")),
+            ),
+            "bootstrap_memory": (
+                self._bootstrap_memory,
+                True,
+                lambda a: (a.get("path"),),
+            ),
+            "memory_status": (
+                self._get_status,
+                False,
+                lambda a: (),
+            ),
+            "get_linked_memories": (
+                self._get_linked_memories,
+                False,
+                lambda a: (a["memory_id"], a.get("link_types")),
+            ),
+            "export_memories": (
+                self._export_memories,
+                True,
+                lambda a: (
+                    a.get("output_path"),
+                    a.get("project"),
+                    a.get("categories"),
+                    a.get("since_days"),
+                    a.get("include_archived", False),
+                ),
+            ),
+            "import_memories": (
+                self._import_memories,
+                True,
+                lambda a: (
+                    a["input_path"],
+                    a.get("dry_run", False),
+                    a.get("skip_duplicates", True),
+                ),
+            ),
+            "bulk_archive": (
+                self._bulk_archive,
+                False,
+                lambda a: (
+                    a.get("memory_ids"),
+                    a.get("category"),
+                    a.get("older_than_days"),
+                    a["reason"],
+                ),
+            ),
+            "delete_memory": (
+                self._delete_memory,
+                True,
+                lambda a: (a["memory_id"], a.get("also_delete_vector", True)),
+            ),
+            "edit_memory": (
+                self._edit_memory,
+                True,
+                lambda a: (
+                    a["memory_id"],
+                    a.get("content"),
+                    a.get("what"),
+                    a.get("why"),
+                    a.get("learned"),
+                    a.get("recompute_embedding", True),
+                ),
+            ),
+        }
+
+        if name not in dispatch:
+            raise ValueError(f"Unknown tool: {name}")
+
+        handler, is_async, args_extractor = dispatch[name]
+        extracted_args = args_extractor(args)
+
+        if is_async:
+            return await handler(*extracted_args)
+        else:
+            return handler(*extracted_args)
+
+    async def _recall(
+        self,
+        query: str,
+        limit: int,
+        project: str | None = None,
+        compact: bool = False,
+        since_days: int | None = None,
+        category: str | None = None,
+    ) -> dict[str, Any]:
+        """Search memories, optionally filtered by project, date, and category."""
+        # Handle 'auto' to detect current project from git
+        if project == "auto":
+            project = _detect_current_project()
+            logger.info(f"Auto-detected project: {project}")
+
+        # Fetch extra results to know how many more are available
+        fetch_limit = limit + 20
+        results = await self.search_engine.search_async(query, fetch_limit, project=project)
+
+        # Post-filter by date if specified
+        if since_days:
+            cutoff = datetime.now(UTC) - timedelta(days=since_days)
+
+            # Handle naive datetimes by assuming UTC
+            def is_after_cutoff(mem_created_at: datetime) -> bool:
+                if mem_created_at.tzinfo is None:
+                    mem_created_at = mem_created_at.replace(tzinfo=UTC)
+                return mem_created_at > cutoff
+
+            results = [r for r in results if is_after_cutoff(r.memory.created_at)]
+
+        # Post-filter by category if specified
+        if category:
+            cat = MemoryCategory(category)
+            results = [r for r in results if r.memory.category == cat]
+
+        # Track what's beyond the limit
+        total_matches = len(results)
+        next_result = results[limit] if len(results) > limit else None
+
+        # Trim to requested limit after filtering
+        results = results[:limit]
+
+        # Cache the returned memories for quick subsequent access
+        self.memory_cache.put_many([r.memory for r in results])
+
+        # Build pagination hint
+        more_available = total_matches - limit if total_matches > limit else 0
+        pagination = {"more_available": more_available}
+        if next_result:
+            pagination["next_score"] = round(next_result.score, 3)
+            pagination["next_category"] = next_result.memory.category.value
+            pagination["next_what"] = next_result.memory.what or next_result.memory.content[:40]
+
+        if compact:
+            # Compact mode: truncated content, essential fields only
+            return {
+                "count": len(results),
+                "pagination": pagination,
+                "results": [
+                    {
+                        "id": r.memory.id,
+                        "content": r.memory.content[:150] + "..."
+                        if len(r.memory.content) > 150
+                        else r.memory.content,
+                        "category": r.memory.category.value,
+                        "what": r.memory.what,
+                        "learned": r.memory.learned,
+                        "age": _format_age(r.memory.created_at),
+                    }
+                    for r in results
+                ],
+            }
+
+        # Build results with linked memories as hints
+        formatted_results = []
+        prefetch_memory_ids = []
+
+        for r in results:
+            result_dict = {
+                "id": r.memory.id,
+                "content": r.memory.content,
+                "category": r.memory.category.value,
+                "score": r.score,
+                "match_type": r.match_type,
+                "source": r.memory.source_file,
+                "what": r.memory.what,
+                "why": r.memory.why,
+                "learned": r.memory.learned,
+                "age": _format_age(r.memory.created_at),
+            }
+
+            # Add minimal hints about linked memories
+            # Just enough to know there's more to explore, not the content itself
+            if r.memory.id:
+                linked_ids = self.sqlite.get_linked_memory_ids(r.memory.id)
+                if linked_ids:
+                    linked_memories = self.sqlite.get_memories_by_ids(linked_ids[:5])
+                    result_dict["has_links"] = len(linked_ids)
+                    result_dict["linked"] = [
+                        {"id": m.id, "type": m.category.value, "what": m.what or m.category.value}
+                        for m in linked_memories.values()
+                    ]
+                    # Schedule prefetch for memories with links
+                    prefetch_memory_ids.append(r.memory.id)
+
+            formatted_results.append(result_dict)
+
+        # Background prefetch linked memories for quick subsequent get_linked_memories calls
+        for memory_id in prefetch_memory_ids[:5]:  # Limit prefetch to top 5 results
+            asyncio.create_task(self.memory_cache.prefetch_linked_async(memory_id))
+
+        return {
+            "count": len(results),
+            "pagination": pagination,
+            "results": formatted_results,
+        }
+
+    async def _remember(
+        self,
+        content: str,
+        category: str,
+        entities: list[str],
+        what: str | None,
+        why: str | None,
+        learned: str | None,
+        project: str | None = None,
+    ) -> dict[str, Any]:
+        """Store a memory immediately, defer embedding and dedup to background.
+
+        This ensures remember() returns instantly without waiting for embedding.
+        Semantic deduplication happens async - if a near-duplicate is found,
+        the new memory is archived with a note.
+        """
+        # Auto-detect project from git if not provided
+        if not project:
+            project = _detect_current_project()
+
+        memory = Memory(
+            category=MemoryCategory(category),
+            content=content,
+            project=project,
+            what=what,
+            why=why,
+            learned=learned,
+            entities=entities,
+        )
+
+        entity_ids = []
+        for ref in entities:
+            entity = self._parse_entity_ref(ref)
+            if entity:
+                entity_id = self.sqlite.upsert_entity(entity)
+                entity_ids.append(entity_id)
+
+        # Store immediately without embedding
+        memory_id = self.sqlite.insert_memory(memory, entity_ids)
+
+        # Cache the new memory immediately
+        memory.id = memory_id
+        self.memory_cache.put(memory)
+
+        # Background: compute embedding, check for duplicates, store vector
+        async def embed_and_dedup():
+            async with MemoryServer._embedding_semaphore:
+                try:
+                    embedding = await self.embeddings.embed_async(memory.embedding_content())
+
+                    # Check for semantic duplicates (0.92 threshold)
+                    similar = self.vectors.search(embedding, limit=3)
+                    for match in similar:
+                        distance = match.get("_distance", 1.0)
+                        similarity = 1.0 / (1.0 + distance)
+                        if similarity > 0.92:
+                            existing_id = match.get("memory_id")
+                            if existing_id:
+                                existing = self.sqlite.get_memory_by_id(existing_id)
+                                if existing and existing.category == memory.category:
+                                    # Archive the new memory as duplicate
+                                    self.sqlite.archive_memory(
+                                        memory_id,
+                                        f"Duplicate of memory {existing_id} (similarity: {similarity:.3f})",
+                                    )
+                                    logger.info(
+                                        f"Memory {memory_id} archived as duplicate of {existing_id}"
+                                    )
+                                    return
+
+                    # No duplicate found, store the embedding
+                    self.vectors.add(
+                        f"mem_{memory_id}", memory_id, memory.embedding_content(), embedding
+                    )
+                except Exception as e:
+                    logger.warning(f"Failed to embed memory {memory_id}: {e}")
+
+        # Queue the embedding task, but limit queue depth
+        if len(MemoryServer._pending_embeddings) >= MAX_PENDING_EMBEDDINGS:
+            logger.warning("Embedding queue full, running synchronously")
+            asyncio.create_task(embed_and_dedup())  # Still async but logged
+        else:
+            task = asyncio.create_task(embed_and_dedup())
+            MemoryServer._pending_embeddings.add(task)
+            task.add_done_callback(MemoryServer._pending_embeddings.discard)
+
+        return {"status": "stored", "memory_id": memory_id}
+
+    async def _get_context(self, entity_ref: str) -> dict[str, Any]:
+        """Get all context for an entity.
+
+        Combines two sources:
+        1. Memories explicitly tagged with the entity
+        2. Semantic search for memories mentioning the entity ref
+        """
+        entity = self._parse_entity_ref(entity_ref)
+        if not entity:
+            return {"error": f"Could not parse entity reference: {entity_ref}"}
+
+        db_entity = self.sqlite.get_entity(entity.ref, entity.type)
+
+        # Get explicitly tagged memories
+        tagged_memories: list[Memory] = []
+        tagged_ids: set[int] = set()
+        if db_entity and db_entity.id is not None:
+            tagged_memories = self.sqlite.get_memories_for_entity(db_entity.id)
+            tagged_ids = {m.id for m in tagged_memories if m.id is not None}
+
+        # Also do semantic search for the entity ref to find mentions
+        # This catches memories that mention the entity but weren't explicitly tagged
+        recall_results = await self.search_engine.search_async(entity_ref, limit=10)
+        related_memories = [
+            r.memory
+            for r in recall_results
+            if r.memory.id not in tagged_ids  # Avoid duplicates
+        ]
+
+        entity_info: dict[str, Any] = {
+            "type": entity.type.value,
+            "ref": entity.ref,
+        }
+
+        if db_entity:
+            entity_info["title"] = db_entity.title
+            if db_entity.metadata:
+                entity_info["state"] = db_entity.metadata.get("state")
+                entity_info["author"] = db_entity.metadata.get("author")
+                entity_info["web_url"] = db_entity.metadata.get("web_url")
+                if db_entity.metadata.get("labels"):
+                    entity_info["labels"] = db_entity.metadata["labels"][:5]
+
+        # Helper to format a memory with optional linked hints
+        def format_memory(m: Memory, compact: bool = False) -> dict[str, Any]:
+            mem_dict: dict[str, Any] = {
+                "id": m.id,
+                "content": m.content[:200] + "..."
+                if compact and len(m.content) > 200
+                else m.content,
+                "category": m.category.value,
+                "what": m.what,
+                "learned": m.learned,
+                "age": _format_age(m.created_at),
+            }
+            if not compact:
+                mem_dict["why"] = m.why
+
+            # Add linked memory hints if available
+            if m.id:
+                linked_ids = self.sqlite.get_linked_memory_ids(m.id)
+                if linked_ids:
+                    linked_memories = self.sqlite.get_memories_by_ids(linked_ids[:3])
+                    mem_dict["has_links"] = len(linked_ids)
+                    mem_dict["linked"] = [
+                        {
+                            "id": lm.id,
+                            "type": lm.category.value,
+                            "what": lm.what or lm.category.value,
+                        }
+                        for lm in linked_memories.values()
+                    ]
+
+            return mem_dict
+
+        result: dict[str, Any] = {
+            "entity": entity_info,
+            "memories": [format_memory(m, compact=False) for m in tagged_memories],
+        }
+
+        # Add related memories from semantic search (if any)
+        # Use compact format to avoid overwhelming output
+        if related_memories:
+            result["related"] = [format_memory(m, compact=True) for m in related_memories[:5]]
+
+        if not tagged_memories and not related_memories:
+            result["note"] = "No memories found"
+
+        return result
+
+    def _get_active_sessions(self) -> dict[str, Any]:
+        """Get active sessions."""
+        sessions = self.session_registry.get_active_sessions()
+        return {
+            "count": len(sessions),
+            "sessions": [
+                {
+                    "id": s.id,
+                    "started_at": s.started_at.isoformat(),
+                    "last_heartbeat": s.last_heartbeat.isoformat(),
+                    "working_on": s.working_on,
+                    "claimed_items": s.claimed_items,
+                }
+                for s in sessions
+            ],
+        }
+
+    def _session_start(self, session_id: str, working_on: str | None) -> dict[str, Any]:
+        """Start a session."""
+        session = self.session_registry.register(session_id, working_on)
+        return {
+            "status": "registered",
+            "session_id": session.id,
+            "started_at": session.started_at.isoformat(),
+        }
+
+    def _session_heartbeat(self, session_id: str) -> dict[str, Any]:
+        """Update session heartbeat."""
+        self.session_registry.heartbeat(session_id)
+        return {"status": "ok", "session_id": session_id}
+
+    async def _session_end(self, session_id: str, summary: str | None) -> dict[str, Any]:
+        """End a session."""
+        if summary:
+            await self._remember(
+                summary,
+                "conversation",
+                [],
+                f"Session {session_id} summary",
+                None,
+                None,
+            )
+        self.session_registry.unregister(session_id)
+        return {"status": "ended", "session_id": session_id}
+
+    def _claim_item(self, session_id: str, item_ref: str) -> dict[str, Any]:
+        """Claim an item."""
+        success = self.session_registry.claim_item(session_id, item_ref)
+        if success:
+            return {"status": "claimed", "item": item_ref, "session": session_id}
+        else:
+            owner = self.session_registry.get_item_owner(item_ref)
+            return {
+                "status": "already_claimed",
+                "item": item_ref,
+                "owner": owner,
+            }
+
+    def _release_item(self, session_id: str, item_ref: str) -> dict[str, Any]:
+        """Release a claimed item."""
+        self.session_registry.release_item(session_id, item_ref)
+        return {"status": "released", "item": item_ref}
+
+    def _get_boot_context(self) -> dict[str, Any]:
+        """Get boot context with comprehensive session startup information."""
+        boot = BootContext()
+
+        if self.config.boot.identity:
+            # Use config values, falling back to auto-detection
+            user = self.config.identity.user
+            primary_project = self.config.identity.primary_project
+
+            # Auto-detect from git if not configured
+            if not user or not primary_project:
+                detected_project = _detect_current_project()
+                if detected_project and not primary_project:
+                    primary_project = detected_project
+
+            boot.identity = {
+                "user": user,
+                "instance": self.config.identity.instance,
+                "primary_project": primary_project,
+            }
+
+        if self.config.boot.active_sessions:
+            boot.active_sessions = self.session_registry.get_active_sessions()
+
+        if self.config.boot.unresolved_blockers:
+            boot.unresolved_blockers = self.sqlite.get_memories_by_category(
+                MemoryCategory.BLOCKER, limit=10
+            )
+
+        if self.config.boot.recent_decisions:
+            boot.recent_decisions = self.sqlite.get_memories_by_category(
+                MemoryCategory.DECISION, limit=5
+            )
+
+        # Load directives contextually: global + current project specific
+        current_project = _detect_current_project()
+        boot.directives = self.sqlite.get_directives_for_context(current_project, limit=10)
+
+        recent_sessions = self._get_recent_session_summaries(limit=3)
+
+        hot_entities = self._get_hot_entities(limit=5)
+
+        procedures = self.sqlite.get_memories_by_category(MemoryCategory.PROCEDURE, limit=3)
+
+        # Get plan summaries (lightweight - just project/count/titles)
+        plan_summaries = self.sqlite.get_plan_summaries()
+
+        return {
+            "identity": boot.identity,
+            "active_sessions": [
+                {
+                    "id": s.id,
+                    "working_on": s.working_on,
+                    "claimed_items": s.claimed_items,
+                }
+                for s in boot.active_sessions
+            ],
+            "unresolved_blockers": [
+                {"content": m.content, "entities": m.entities, "age": _format_age(m.created_at)}
+                for m in boot.unresolved_blockers
+            ],
+            "recent_decisions": [
+                {"content": m.content, "what": m.what, "age": _format_age(m.created_at)}
+                for m in boot.recent_decisions
+            ],
+            "directives": [
+                {
+                    "content": m.content,
+                    "what": m.what,
+                    "scope": m.project or "global",
+                    "age": _format_age(m.created_at),
+                }
+                for m in boot.directives
+            ],
+            "recent_sessions": recent_sessions,
+            "hot_entities": hot_entities,
+            "key_procedures": [
+                {"content": m.content[:200], "what": m.what, "age": _format_age(m.created_at)}
+                for m in procedures
+            ],
+            "active_plans": plan_summaries if plan_summaries else None,
+            "remember_prompts": {
+                "instruction": "ACTIVELY USE MEMORY during this session. Don't wait to be asked.",
+                "when_to_remember": [
+                    "Decision made? → remember(category='decision', what='chose X', why='because Y')",
+                    "Hit a blocker? → remember(category='blocker', what='blocked by X')",
+                    "Learned something? → remember(category='procedure', what='how to X', learned='key insight')",
+                    "Interesting fact? → remember(category='fact', what='X does Y')",
+                    "Long-term goal? → remember(category='plan', what='goal X', why='to achieve Y')",
+                ],
+                "tips": [
+                    "Include entity refs (!MR, #issue, &epic) to link memories",
+                    "The 'learned' field captures the key takeaway for future sessions",
+                    "Blockers can be resolved later with resolve_blocker(memory_id)",
+                ],
+            },
+            "linked_memories": {
+                "what": "Search results include 'linked' hints showing related memories you didn't search for",
+                "when_to_fetch": [
+                    "type='directive' → ALWAYS fetch, these are standing instructions",
+                    "type='plan' → fetch if relevant to current work context",
+                    "type='decision' → fetch to avoid contradicting prior choices",
+                    "type='blocker' → fetch if working on related entity",
+                    "type='procedure' → fetch if about to do that task",
+                ],
+                "how": "Call get_linked_memories(memory_id) to fetch full content",
+            },
+            "plans_hint": "Use recall(query, category='plan') to load full plan details"
+            if plan_summaries
+            else None,
+        }
+
+    def _get_recent_session_summaries(self, limit: int = 3) -> list[dict[str, Any]]:
+        """Get summaries of recent conversation sessions."""
+        recent = self.sqlite.get_memories_by_category(MemoryCategory.CONVERSATION, limit=limit)
+        summaries = []
+        for m in recent:
+            lines = m.content.split("\n")
+            title = lines[0].replace("Session: ", "") if lines else "Unknown"
+            topics = ""
+            outcome = ""
+            for line in lines:
+                if line.startswith("Topics:"):
+                    topics = line.replace("Topics:", "").strip()
+                elif line.startswith("Outcome:"):
+                    outcome = line.replace("Outcome:", "").strip()
+
+            summaries.append(
+                {
+                    "title": title,
+                    "topics": topics,
+                    "outcome": outcome,
+                    "when": m.created_at.isoformat(),
+                }
+            )
+        return summaries
+
+    def _get_hot_entities(self, limit: int = 5) -> list[dict[str, Any]]:
+        """Get entities with most recent activity/mentions."""
+        from collections import Counter
+
+        recent_memories = self.sqlite.get_memories_by_category(
+            MemoryCategory.CONVERSATION, limit=20
+        )
+
+        entity_counts: Counter[str] = Counter()
+        for m in recent_memories:
+            for entity in m.entities:
+                entity_counts[entity] += 1
+
+        hot = []
+        for ref, count in entity_counts.most_common(limit):
+            entity = self._parse_entity_ref(ref)
+            if entity:
+                db_entity = self.sqlite.get_entity(entity.ref, entity.type)
+                hot.append(
+                    {
+                        "ref": ref,
+                        "type": entity.type.value,
+                        "title": db_entity.title if db_entity else None,
+                        "mentions": count,
+                    }
+                )
+
+        return hot
+
+    def _search_history(self, query: str, category: str | None, limit: int) -> dict[str, Any]:
+        """Search history with optional category filter."""
+        if category:
+            memories = self.sqlite.get_memories_by_category(MemoryCategory(category), limit)
+            filtered = [m for m in memories if query.lower() in m.content.lower()]
+            return {
+                "count": len(filtered),
+                "results": [
+                    {
+                        "content": m.content,
+                        "category": m.category.value,
+                        "what": m.what,
+                        "age": _format_age(m.created_at),
+                    }
+                    for m in filtered
+                ],
+            }
+        else:
+            return self._recall(query, limit)
+
+    async def _ingest_file(self, file_path: str) -> dict[str, Any]:
+        """Ingest a file manually.
+
+        Creates memories for each chunk and links them sequentially
+        with strong (0.95) SEQUENCE links to preserve document structure.
+        Embeddings are created asynchronously to avoid blocking.
+        """
+        path = Path(file_path).expanduser()
+        if not path.exists():
+            return {"error": f"File not found: {file_path}"}
+
+        doc = self.parser.parse_file(path)
+
+        entity_ids = []
+        for entity_type, ref in doc.entities:
+            entity = Entity(type=entity_type, ref=ref)
+            entity_id = self.sqlite.upsert_entity(entity)
+            entity_ids.append(entity_id)
+
+        # Insert memories first (fast), then embed asynchronously
+        memory_ids: list[int] = []
+        memories_to_embed: list[tuple[int, str]] = []
+
+        for memory in doc.memories:
+            memory_id = self.sqlite.insert_memory(memory, entity_ids)
+            memory.id = memory_id
+            self.memory_cache.put(memory)
+            memory_ids.append(memory_id)
+            memories_to_embed.append((memory_id, memory.embedding_content()))
+
+        # Create bidirectional sequential links between chunks from the same file
+        # This allows navigation up/down the document from any chunk
+        links_created = 0
+        for i in range(len(memory_ids) - 1):
+            # Forward link: chunk i → chunk i+1
+            forward_link = MemoryLink(
+                source_memory_id=memory_ids[i],
+                target_memory_id=memory_ids[i + 1],
+                link_type=LinkType.SEQUENCE,
+                strength=0.95,  # Strong link - same document
+                reason=f"Next section in {path.name}",
+            )
+            if self.sqlite.insert_link(forward_link):
+                links_created += 1
+
+            # Backward link: chunk i+1 → chunk i
+            backward_link = MemoryLink(
+                source_memory_id=memory_ids[i + 1],
+                target_memory_id=memory_ids[i],
+                link_type=LinkType.SEQUENCE,
+                strength=0.95,  # Strong link - same document
+                reason=f"Previous section in {path.name}",
+            )
+            if self.sqlite.insert_link(backward_link):
+                links_created += 1
+
+        # Embed asynchronously - don't block the response
+        async def embed_memories():
+            for memory_id, content in memories_to_embed:
+                try:
+                    embedding = await self.embeddings.embed_async(content)
+                    self.vectors.add(f"mem_{memory_id}", memory_id, content, embedding)
+                except Exception as e:
+                    logger.warning(f"Failed to embed memory {memory_id}: {e}")
+
+        # Start embedding in background
+        asyncio.create_task(embed_memories())
+
+        return {
+            "status": "ingested",
+            "file": str(path),
+            "entities_found": len(doc.entities),
+            "memories_created": len(memory_ids),
+            "sequential_links": links_created,
+            "note": "Embeddings processing in background",
+        }
+
+    def _parse_entity_ref(self, ref: str) -> Entity | None:
+        """Parse an entity reference string."""
+        return Entity.from_ref(ref)
+
+    async def _enrich_entity(self, entity_ref: str, project: str | None = None) -> dict[str, Any]:
+        """Enrich an entity with GitLab metadata."""
+        entity = self._parse_entity_ref(entity_ref)
+        if not entity:
+            return {"error": f"Could not parse entity reference: {entity_ref}"}
+
+        entity.project = project
+
+        enriched = await self.enricher.enrich_entity(entity)
+        self.sqlite.upsert_entity(enriched)
+
+        return {
+            "status": "enriched",
+            "entity": {
+                "type": enriched.type.value,
+                "ref": enriched.ref,
+                "title": enriched.title,
+                "project": enriched.project,
+                "metadata": enriched.metadata,
+            },
+        }
+
+    def _resolve_blocker(self, memory_id: int) -> dict[str, Any]:
+        """Mark a blocker as resolved."""
+        memory = self.sqlite.get_memory_by_id(memory_id)
+        if not memory:
+            return {"error": f"Memory {memory_id} not found"}
+        if memory.category != MemoryCategory.BLOCKER:
+            return {"error": f"Memory {memory_id} is not a blocker (is {memory.category.value})"}
+        if memory.resolved_at:
+            return {"status": "already_resolved", "memory_id": memory_id}
+
+        success = self.sqlite.resolve_memory(memory_id)
+        if success:
+            return {"status": "resolved", "memory_id": memory_id}
+        return {"error": "Failed to resolve memory"}
+
+    def _unresolve_blocker(self, memory_id: int) -> dict[str, Any]:
+        """Mark a blocker as unresolved."""
+        memory = self.sqlite.get_memory_by_id(memory_id)
+        if not memory:
+            return {"error": f"Memory {memory_id} not found"}
+
+        success = self.sqlite.unresolve_memory(memory_id)
+        if success:
+            return {"status": "unresolved", "memory_id": memory_id}
+        return {"error": "Failed to unresolve memory"}
+
+    def _consolidate_memory(self, project: str | None, days_stale: int) -> dict[str, Any]:
+        """Queue memory consolidation analysis to run in background.
+
+        Returns immediately with status. Results are stored as a 'fact' memory
+        that can be retrieved via recall("consolidation report").
+        """
+        if project == "auto":
+            project = _detect_current_project()
+
+        # Check for recent consolidation report
+        recent_report = self.sqlite.get_recent_consolidation_report()
+        if recent_report:
+            return {
+                "status": "recent_report_available",
+                "report_age": _format_age(recent_report.created_at),
+                "memory_id": recent_report.id,
+                "hint": "Use recall('consolidation report') or get_linked_memories to view",
+            }
+
+        # Queue background analysis
+        async def run_consolidation():
+            try:
+                stats = self.sqlite.get_consolidation_stats(project, days_stale)
+
+                # Duplicate detection in background
+                recent_memories = self.sqlite.get_recent_memories_for_dedup(
+                    project=project, limit=200, days=min(days_stale, 14)
+                )
+
+                potential_duplicates = []
+                content_words: dict[int, set[str]] = {}
+                for m in recent_memories:
+                    words = set(re.findall(r"\w{4,}", m.content.lower()))
+                    content_words[m.id] = words
+
+                for i, m1 in enumerate(recent_memories):
+                    for m2 in recent_memories[i + 1 : i + 31]:
+                        words1 = content_words.get(m1.id, set())
+                        words2 = content_words.get(m2.id, set())
+                        if not words1 or not words2:
+                            continue
+
+                        overlap = len(words1 & words2) / min(len(words1), len(words2))
+                        if overlap > 0.7:
+                            potential_duplicates.append(
+                                {
+                                    "ids": [m1.id, m2.id],
+                                    "similarity": round(overlap, 2),
+                                }
+                            )
+                            if len(potential_duplicates) >= 10:
+                                break
+                    if len(potential_duplicates) >= 10:
+                        break
+
+                # Build report content
+                stale_summary = "\n".join(
+                    f"- [{r['id']}] {r['category']}: {r['content'][:60]}... ({r['age']})"
+                    for r in stats["stale_records"][:10]
+                )
+                dup_summary = "\n".join(
+                    f"- IDs {d['ids']}: {d['similarity']:.0%} similar"
+                    for d in potential_duplicates[:10]
+                )
+
+                report_content = f"""Memory Consolidation Report ({datetime.now(UTC).strftime("%Y-%m-%d %H:%M")})
+
+Total: {stats["total"]} memories
+By category: {stats["by_category"]}
+
+Stale records ({len(stats["stale_records"])} found, showing 10):
+{stale_summary or "(none)"}
+
+Potential duplicates ({len(potential_duplicates)} found):
+{dup_summary or "(none)"}
+
+Actions:
+- archive_memory(id, reason) to archive stale records
+- delete_memory(id) to remove duplicates
+- resolve_blocker(id) to mark resolved blockers"""
+
+                # Store as fact memory
+                report_memory = Memory(
+                    category=MemoryCategory.FACT,
+                    content=report_content,
+                    what="Memory consolidation report",
+                    why="Periodic health check of memory system",
+                    project=project,
+                    expires_at=datetime.now(UTC) + timedelta(days=7),  # Auto-expire after 7 days
+                )
+                memory_id = self.sqlite.insert_memory(report_memory)
+                report_memory.id = memory_id
+                self.memory_cache.put(report_memory)
+
+                logger.info(f"Consolidation report stored as memory {memory_id}")
+
+            except Exception as e:
+                logger.exception(f"Consolidation failed: {e}")
+
+        task = asyncio.create_task(run_consolidation())
+        task_id = _background_tasks.register("consolidate_memory", task)
+
+        return {
+            "status": "queued",
+            "task_id": task_id,
+            "message": "Consolidation analysis running in background",
+            "hint": "Results will be stored as a memory. Use recall('consolidation report') to retrieve.",
+        }
+
+    async def _log_session(
+        self,
+        summary: str,
+        learnings: list[str],
+        entities: list[str],
+        project: str | None,
+    ) -> dict[str, Any]:
+        """Log a session summary with learnings."""
+        if project == "auto" or project is None:
+            project = _detect_current_project()
+
+        # Build content from summary and learnings
+        content_parts = [f"Session Summary: {summary}"]
+        if learnings:
+            content_parts.append("Learnings:")
+            for learning in learnings:
+                content_parts.append(f"- {learning}")
+
+        content = "\n".join(content_parts)
+
+        # Store as a conversation memory
+        memory = Memory(
+            category=MemoryCategory.CONVERSATION,
+            content=content,
+            what=summary[:100] if len(summary) > 100 else summary,
+            learned=learnings[0] if learnings else None,
+            project=project,
+        )
+
+        # Parse entity refs
+        entity_ids = []
+        for ref in entities:
+            entity = self._parse_entity_ref(ref)
+            if entity:
+                entity_id = self.sqlite.upsert_entity(entity)
+                entity_ids.append(entity_id)
+
+        memory_id = self.sqlite.insert_memory(memory, entity_ids)
+
+        # Cache immediately
+        memory.id = memory_id
+        self.memory_cache.put(memory)
+
+        # Generate embedding in background with bounded concurrency
+        async def embed_later():
+            async with MemoryServer._embedding_semaphore:
+                try:
+                    embedding = await self.embeddings.embed_async(memory.embedding_content())
+                    self.vectors.add(
+                        f"mem_{memory_id}", memory_id, memory.embedding_content(), embedding
+                    )
+                except Exception as e:
+                    logger.warning(f"Failed to embed session log: {e}")
+
+        task = asyncio.create_task(embed_later())
+        MemoryServer._pending_embeddings.add(task)
+        task.add_done_callback(MemoryServer._pending_embeddings.discard)
+
+        return {
+            "status": "logged",
+            "memory_id": memory_id,
+            "summary": summary,
+            "learnings_count": len(learnings),
+            "entities_linked": len(entity_ids),
+        }
+
+    def _get_status(self) -> dict[str, Any]:
+        """Get memory system status for introspection."""
+        # Pending embeddings queue
+        pending_count = len(MemoryServer._pending_embeddings)
+        semaphore_available = (
+            MemoryServer._embedding_semaphore._value if MemoryServer._embedding_semaphore else 4
+        )
+
+        # Storage stats
+        db_size = self.config.db_path.stat().st_size if self.config.db_path.exists() else 0
+        vectors_size = (
+            sum(f.stat().st_size for f in self.config.vectors_path.rglob("*") if f.is_file())
+            if self.config.vectors_path.exists()
+            else 0
+        )
+
+        # Vector version count
+        try:
+            table = self.vectors.db.open_table("memories")
+            vector_versions = len(table.list_versions())
+        except Exception:
+            vector_versions = None
+
+        # Memory counts by category
+        category_counts = {}
+        for cat in MemoryCategory:
+            with self.sqlite._get_conn() as conn:
+                row = conn.execute(
+                    "SELECT COUNT(*) FROM memories WHERE category = ? AND resolved_at IS NULL",
+                    (cat.value,),
+                ).fetchone()
+                category_counts[cat.value] = row[0] if row else 0
+
+        # Daemon status
+        daemon_status = None
+        if self.daemon:
+            daemon_status = {
+                "running": self.daemon.is_running,
+            }
+
+        # Try to get active client info from http_server
+        clients_info = None
+        try:
+            from opencode_memory.http_server import get_active_clients
+
+            clients_info = get_active_clients()
+        except ImportError:
+            pass  # Not running via http_server
+
+        # Get running background tasks
+        running_tasks = _background_tasks.get_running_tasks()
+
+        result = {
+            "embedding_queue": {
+                "pending": pending_count,
+                "max_concurrent": 4,
+                "slots_available": semaphore_available,
+                "status": "idle" if pending_count == 0 else "processing",
+            },
+            "storage": {
+                "db_size_mb": round(db_size / (1024 * 1024), 2),
+                "vectors_size_mb": round(vectors_size / (1024 * 1024), 2),
+                "vector_versions": vector_versions,
+                "db_path": str(self.config.db_path),
+            },
+            "memories": category_counts,
+            "daemon": daemon_status,
+            "links": self.sqlite.get_link_stats(),
+            "cache": self.memory_cache.get_stats(),
+            "background_tasks": running_tasks,
+        }
+
+        if clients_info:
+            result["clients"] = clients_info
+
+        return result
+
+    def _archive_memory(self, memory_id: int, reason: str | None) -> dict[str, Any]:
+        """Archive a memory record."""
+        memory = self.sqlite.get_memory_by_id(memory_id)
+        if not memory:
+            return {"error": f"Memory {memory_id} not found"}
+
+        success = self.sqlite.archive_memory(memory_id, reason or "No reason provided")
+        if success:
+            # Invalidate cache
+            self.memory_cache.invalidate(memory_id)
+            return {
+                "status": "archived",
+                "memory_id": memory_id,
+                "reason": reason,
+            }
+        return {"error": "Failed to archive memory"}
+
+    async def _delete_memory(
+        self, memory_id: int, also_delete_vector: bool = True
+    ) -> dict[str, Any]:
+        """Permanently delete a memory."""
+        memory = self.sqlite.get_memory_by_id(memory_id)
+        if not memory:
+            return {"error": f"Memory {memory_id} not found"}
+
+        # Delete from vector store first
+        if also_delete_vector:
+            try:
+                self.vectors.delete_by_memory_id(memory_id)
+            except Exception as e:
+                logger.warning(f"Failed to delete vector for memory {memory_id}: {e}")
+
+        # Delete from SQLite (includes FTS and links)
+        success = self.sqlite.delete_memory(memory_id)
+        if success:
+            # Invalidate cache
+            self.memory_cache.invalidate(memory_id)
+            return {
+                "status": "deleted",
+                "memory_id": memory_id,
+                "vector_deleted": also_delete_vector,
+            }
+        return {"error": "Failed to delete memory"}
+
+    async def _edit_memory(
+        self,
+        memory_id: int,
+        content: str | None = None,
+        what: str | None = None,
+        why: str | None = None,
+        learned: str | None = None,
+        recompute_embedding: bool = True,
+    ) -> dict[str, Any]:
+        """Edit a memory's content or metadata."""
+        memory = self.sqlite.get_memory_by_id(memory_id)
+        if not memory:
+            return {"error": f"Memory {memory_id} not found"}
+
+        # Update in SQLite
+        success = self.sqlite.update_memory(
+            memory_id,
+            content=content,
+            what=what,
+            why=why,
+            learned=learned,
+        )
+        if not success:
+            return {"error": "Failed to update memory"}
+
+        # Recompute embedding if content changed
+        if content is not None and recompute_embedding:
+            try:
+                # Build new embedding content
+                updated_memory = self.sqlite.get_memory_by_id(memory_id)
+                if updated_memory:
+                    new_embedding = await self.embeddings.embed_async(
+                        updated_memory.embedding_content()
+                    )
+                    # Delete old and add new vector
+                    self.vectors.delete_by_memory_id(memory_id)
+                    self.vectors.add(
+                        f"mem_{memory_id}",
+                        memory_id,
+                        updated_memory.embedding_content(),
+                        new_embedding,
+                    )
+            except Exception as e:
+                logger.warning(f"Failed to recompute embedding for memory {memory_id}: {e}")
+                return {
+                    "status": "partial",
+                    "memory_id": memory_id,
+                    "updated_fields": [
+                        f for f in ["content", "what", "why", "learned"] if locals().get(f)
+                    ],
+                    "warning": f"Content updated but embedding failed: {e}",
+                }
+
+        # Invalidate cache so next fetch gets updated version
+        self.memory_cache.invalidate(memory_id)
+
+        updated_fields = [
+            name
+            for name, value in [
+                ("content", content),
+                ("what", what),
+                ("why", why),
+                ("learned", learned),
+            ]
+            if value is not None
+        ]
+
+        return {
+            "status": "updated",
+            "memory_id": memory_id,
+            "updated_fields": updated_fields,
+            "embedding_recomputed": content is not None and recompute_embedding,
+        }
+
+    async def _bootstrap_memory(self, path: str | None) -> dict[str, Any]:
+        """Bootstrap project memory by scanning common project files."""
+        import json
+        import tomllib
+
+        project_path = Path(path) if path else Path.cwd()
+        if not project_path.exists():
+            return {"error": f"Path not found: {project_path}"}
+
+        project_name = _detect_current_project() or project_path.name
+        facts_created = 0
+        facts_skipped = 0
+        scanned_files = []
+
+        existing_facts = self.sqlite.get_memories_by_category(
+            MemoryCategory.FACT, limit=500, project=project_name
+        )
+        existing_content = {m.content.lower() for m in existing_facts}
+
+        async def store_fact(content: str, what: str) -> bool:
+            nonlocal facts_created, facts_skipped
+            if content.lower() in existing_content:
+                facts_skipped += 1
+                return False
+
+            await self._remember(
+                content=content,
+                category="fact",
+                entities=[],
+                what=what,
+                why="Bootstrapped from project files",
+                learned=None,
+                project=project_name,
+            )
+            existing_content.add(content.lower())
+            facts_created += 1
+            return True
+
+        readme = project_path / "README.md"
+        if readme.exists():
+            scanned_files.append("README.md")
+            text = readme.read_text(encoding="utf-8", errors="ignore")
+            lines = text.split("\n")
+            title = None
+            description_lines = []
+
+            for line in lines[:20]:
+                if line.startswith("# ") and not title:
+                    title = line[2:].strip()
+                elif title and line.strip() and not line.startswith("#"):
+                    description_lines.append(line.strip())
+                    if len(description_lines) >= 3:
+                        break
+
+            if title:
+                desc = " ".join(description_lines)[:200] if description_lines else ""
+                content = f"Project '{title}': {desc}" if desc else f"Project: {title}"
+                await store_fact(content, f"Project description for {project_name}")
+
+        pkg_json = project_path / "package.json"
+        if pkg_json.exists():
+            scanned_files.append("package.json")
+            try:
+                data = json.loads(pkg_json.read_text())
+                name = data.get("name", "")
+                desc = data.get("description", "")
+                if name or desc:
+                    await store_fact(
+                        f"Node.js project '{name}': {desc}",
+                        "package.json description",
+                    )
+
+                deps = list(data.get("dependencies", {}).keys())[:10]
+                dev_deps = list(data.get("devDependencies", {}).keys())[:5]
+                if deps:
+                    await store_fact(
+                        f"Main dependencies: {', '.join(deps)}",
+                        "Key npm dependencies",
+                    )
+                if dev_deps:
+                    await store_fact(
+                        f"Dev dependencies: {', '.join(dev_deps)}",
+                        "Dev npm dependencies",
+                    )
+
+                scripts = list(data.get("scripts", {}).keys())
+                if scripts:
+                    await store_fact(
+                        f"Available npm scripts: {', '.join(scripts)}",
+                        "npm scripts",
+                    )
+            except (json.JSONDecodeError, KeyError):
+                pass
+
+        pyproject = project_path / "pyproject.toml"
+        if pyproject.exists():
+            scanned_files.append("pyproject.toml")
+            try:
+                data = tomllib.loads(pyproject.read_text())
+                project_data = data.get("project", {})
+                name = project_data.get("name", "")
+                desc = project_data.get("description", "")
+                if name or desc:
+                    await store_fact(
+                        f"Python project '{name}': {desc}",
+                        "pyproject.toml description",
+                    )
+
+                deps = project_data.get("dependencies", [])[:10]
+                if deps:
+                    dep_names = [
+                        d.split("[")[0].split(">")[0].split("<")[0].split("=")[0].strip()
+                        for d in deps
+                    ]
+                    await store_fact(
+                        f"Python dependencies: {', '.join(dep_names)}",
+                        "Key Python dependencies",
+                    )
+            except Exception:
+                pass
+
+        gemfile = project_path / "Gemfile"
+        if gemfile.exists():
+            scanned_files.append("Gemfile")
+            try:
+                text = gemfile.read_text()
+                gems = re.findall(r"gem ['\"]([^'\"]+)['\"]", text)[:10]
+                if gems:
+                    await store_fact(
+                        f"Ruby gems: {', '.join(gems)}",
+                        "Key Ruby dependencies",
+                    )
+            except Exception:
+                pass
+
+        cargo = project_path / "Cargo.toml"
+        if cargo.exists():
+            scanned_files.append("Cargo.toml")
+            try:
+                data = tomllib.loads(cargo.read_text())
+                pkg = data.get("package", {})
+                name = pkg.get("name", "")
+                desc = pkg.get("description", "")
+                if name or desc:
+                    await store_fact(
+                        f"Rust project '{name}': {desc}",
+                        "Cargo.toml description",
+                    )
+
+                deps = list(data.get("dependencies", {}).keys())[:10]
+                if deps:
+                    await store_fact(
+                        f"Rust dependencies: {', '.join(deps)}",
+                        "Key Rust dependencies",
+                    )
+            except Exception:
+                pass
+
+        go_mod = project_path / "go.mod"
+        if go_mod.exists():
+            scanned_files.append("go.mod")
+            try:
+                text = go_mod.read_text()
+                module_match = re.search(r"^module\s+(\S+)", text, re.MULTILINE)
+                if module_match:
+                    await store_fact(
+                        f"Go module: {module_match.group(1)}",
+                        "Go module path",
+                    )
+
+                requires = re.findall(r"^\s+(\S+)\s+v", text, re.MULTILINE)[:10]
+                if requires:
+                    await store_fact(
+                        f"Go dependencies: {', '.join(requires)}",
+                        "Key Go dependencies",
+                    )
+            except Exception:
+                pass
+
+        return {
+            "status": "bootstrapped",
+            "project": project_name,
+            "path": str(project_path),
+            "files_scanned": scanned_files,
+            "facts_created": facts_created,
+            "facts_skipped": facts_skipped,
+            "note": "Run recall('project') to see stored facts"
+            if facts_created
+            else "No new facts to store",
+        }
+
+    def _get_linked_memories(
+        self, memory_id: int, link_types: list[str] | None = None
+    ) -> dict[str, Any]:
+        """Get all memories linked to a specific memory.
+
+        Uses the memory cache for fast retrieval of prefetched linked memories.
+        """
+        from opencode_memory.models import LinkType
+
+        # Try cache first for the source memory
+        memory = self.memory_cache.get(memory_id)
+        if not memory:
+            memory = self.sqlite.get_memory_by_id(memory_id)
+            if memory:
+                self.memory_cache.put(memory)
+        if not memory:
+            return {"error": f"Memory {memory_id} not found"}
+
+        # Convert string types to LinkType enum
+        type_filter = None
+        if link_types:
+            type_filter = [LinkType(t) for t in link_types]
+
+        # Get all links for this memory
+        links = self.sqlite.get_all_links_for_memory(memory_id)
+
+        if type_filter:
+            links = [lnk for lnk in links if lnk.link_type in type_filter]
+
+        if not links:
+            return {
+                "memory_id": memory_id,
+                "memory_what": memory.what,
+                "linked_memories": [],
+                "note": "No links found for this memory",
+            }
+
+        # Collect unique linked memory IDs
+        linked_ids: list[int] = []
+        link_by_id: dict[int, Any] = {}
+        for link in links:
+            other_id = (
+                link.target_memory_id
+                if link.source_memory_id == memory_id
+                else link.source_memory_id
+            )
+            if other_id not in link_by_id:
+                linked_ids.append(other_id)
+                link_by_id[other_id] = link
+
+        # Try cache first for linked memories
+        cached = self.memory_cache.get_many(linked_ids)
+        uncached_ids = [mid for mid in linked_ids if mid not in cached]
+
+        # Fetch uncached from database
+        if uncached_ids:
+            fetched = self.sqlite.get_memories_by_ids(uncached_ids)
+            self.memory_cache.put_many(list(fetched.values()))
+            cached.update(fetched)
+
+        # Build response
+        linked_data = []
+        for other_id in linked_ids:
+            other_memory = cached.get(other_id)
+            if not other_memory:
+                continue
+
+            link = link_by_id[other_id]
+            linked_data.append(
+                {
+                    "id": other_memory.id,
+                    "content": other_memory.content,
+                    "category": other_memory.category.value,
+                    "what": other_memory.what,
+                    "why": other_memory.why,
+                    "learned": other_memory.learned,
+                    "age": _format_age(other_memory.created_at),
+                    "link_type": link.link_type.value,
+                    "link_strength": link.strength,
+                    "link_reason": link.reason,
+                }
+            )
+
+        return {
+            "memory_id": memory_id,
+            "memory_what": memory.what,
+            "linked_memories": linked_data,
+            "total_links": len(linked_data),
+        }
+
+    async def _export_memories(
+        self,
+        output_path: str | None,
+        project: str | None,
+        categories: list[str] | None,
+        since_days: int | None,
+        include_archived: bool,
+    ) -> dict[str, Any]:
+        """Queue memory export to run in background.
+
+        Returns immediately. Results stored as fact memory when complete.
+        """
+        import json
+        from datetime import timedelta
+
+        if project == "auto":
+            project = _detect_current_project()
+
+        # Default output path
+        if not output_path:
+            output_path = str(Path.home() / "opencode-memory-export.json")
+        else:
+            output_path = str(Path(output_path).expanduser())
+
+        async def do_export():
+            try:
+                all_memories = self.sqlite.get_all_memories(
+                    project=project, include_archived=include_archived, limit=10000
+                )
+
+                if categories:
+                    cat_set = {MemoryCategory(c) for c in categories}
+                    all_memories = [m for m in all_memories if m.category in cat_set]
+
+                if since_days:
+                    cutoff = datetime.now(UTC) - timedelta(days=since_days)
+
+                    # Handle naive datetimes by assuming UTC
+                    def is_after_cutoff(mem_created_at: datetime) -> bool:
+                        if mem_created_at.tzinfo is None:
+                            mem_created_at = mem_created_at.replace(tzinfo=UTC)
+                        return mem_created_at > cutoff
+
+                    all_memories = [m for m in all_memories if is_after_cutoff(m.created_at)]
+
+                all_entities = []
+                all_links = []
+                entity_ids_seen = set()
+
+                for memory in all_memories:
+                    if memory.id:
+                        links = self.sqlite.get_all_links_for_memory(memory.id)
+                        for link in links:
+                            all_links.append(
+                                {
+                                    "source_memory_id": link.source_memory_id,
+                                    "target_memory_id": link.target_memory_id,
+                                    "link_type": link.link_type.value,
+                                    "strength": link.strength,
+                                    "reason": link.reason,
+                                }
+                            )
+
+                with self.sqlite._get_conn() as conn:
+                    cursor = conn.execute("SELECT * FROM entities")
+                    for row in cursor.fetchall():
+                        if row["id"] not in entity_ids_seen:
+                            entity_ids_seen.add(row["id"])
+                            all_entities.append(
+                                {
+                                    "id": row["id"],
+                                    "type": row["type"],
+                                    "ref": row["ref"],
+                                    "project": row["project"],
+                                    "title": row["title"],
+                                    "metadata": row["metadata"],
+                                }
+                            )
+
+                export_data = {
+                    "version": "1.0",
+                    "exported_at": datetime.now(UTC).isoformat(),
+                    "filters": {
+                        "project": project,
+                        "categories": categories,
+                        "since_days": since_days,
+                        "include_archived": include_archived,
+                    },
+                    "memories": [
+                        {
+                            "id": m.id,
+                            "category": m.category.value,
+                            "content": m.content,
+                            "what": m.what,
+                            "why": m.why,
+                            "learned": m.learned,
+                            "project": m.project,
+                            "source_file": m.source_file,
+                            "created_at": m.created_at.isoformat(),
+                            "resolved_at": m.resolved_at.isoformat() if m.resolved_at else None,
+                            "entities": m.entities,
+                        }
+                        for m in all_memories
+                    ],
+                    "entities": all_entities,
+                    "links": all_links,
+                }
+
+                Path(output_path).write_text(json.dumps(export_data, indent=2))
+
+                # Store completion as fact
+                result_memory = Memory(
+                    category=MemoryCategory.FACT,
+                    content=f"Export completed: {len(all_memories)} memories, {len(all_entities)} entities, {len(all_links)} links → {output_path}",
+                    what="Memory export completed",
+                    expires_at=datetime.now(UTC) + timedelta(days=1),
+                )
+                self.sqlite.insert_memory(result_memory)
+                logger.info(f"Export completed: {output_path}")
+
+            except Exception as e:
+                logger.exception(f"Export failed: {e}")
+
+        task = asyncio.create_task(do_export())
+        task_id = _background_tasks.register("export_memories", task)
+
+        return {
+            "status": "queued",
+            "task_id": task_id,
+            "path": output_path,
+            "message": "Export running in background",
+            "hint": "Check file or recall('export completed') when done",
+        }
+
+    async def _import_memories(
+        self,
+        input_path: str,
+        dry_run: bool,
+        skip_duplicates: bool,
+    ) -> dict[str, Any]:
+        """Queue memory import to run in background.
+
+        Dry run returns immediately with counts. Full import runs async.
+        """
+        import json
+
+        path = Path(input_path).expanduser()
+        if not path.exists():
+            return {"error": f"File not found: {input_path}"}
+
+        try:
+            data = json.loads(path.read_text())
+        except json.JSONDecodeError as e:
+            return {"error": f"Invalid JSON: {e}"}
+
+        version = data.get("version", "unknown")
+        memories_data = data.get("memories", [])
+        entities_data = data.get("entities", [])
+        links_data = data.get("links", [])
+
+        # Dry run: quick count without loading all existing memories
+        if dry_run:
+            return {
+                "status": "dry_run",
+                "version": version,
+                "memories_to_import": len(memories_data),
+                "entities_to_import": len(entities_data),
+                "links_to_import": len(links_data),
+                "note": "Run without dry_run=true to import",
+            }
+
+        # Queue the actual import
+        async def do_import():
+            try:
+                imported = 0
+                skipped = 0
+                errors = []
+
+                existing_hashes = set()
+                if skip_duplicates:
+                    existing = self.sqlite.get_all_memories(include_archived=False, limit=10000)
+                    existing_hashes = {hash(m.content.strip().lower()) for m in existing}
+
+                memory_id_map: dict[int, int] = {}
+                entity_id_map: dict[int, int] = {}
+
+                for entity_data in entities_data:
+                    entity = Entity(
+                        type=EntityType(entity_data["type"]),
+                        ref=entity_data["ref"],
+                        project=entity_data.get("project"),
+                        title=entity_data.get("title"),
+                    )
+                    new_id = self.sqlite.upsert_entity(entity)
+                    if entity_data.get("id"):
+                        entity_id_map[entity_data["id"]] = new_id
+
+                memories_to_import = []
+                for mem_data in memories_data:
+                    content = mem_data.get("content", "")
+                    content_hash = hash(content.strip().lower())
+
+                    if skip_duplicates and content_hash in existing_hashes:
+                        skipped += 1
+                        continue
+
+                    memories_to_import.append((mem_data, content, content_hash))
+
+                batch_size = 50
+                for batch_start in range(0, len(memories_to_import), batch_size):
+                    batch = memories_to_import[batch_start : batch_start + batch_size]
+
+                    batch_memories = []
+                    for mem_data, content, content_hash in batch:
+                        try:
+                            memory = Memory(
+                                category=MemoryCategory(mem_data["category"]),
+                                content=content,
+                                what=mem_data.get("what"),
+                                why=mem_data.get("why"),
+                                learned=mem_data.get("learned"),
+                                project=mem_data.get("project"),
+                                source_file=mem_data.get("source_file"),
+                                entities=mem_data.get("entities", []),
+                            )
+
+                            entity_ids = []
+                            for ref in memory.entities:
+                                entity = Entity.from_ref(ref)
+                                if entity:
+                                    entity_id = self.sqlite.upsert_entity(entity)
+                                    entity_ids.append(entity_id)
+
+                            new_id = self.sqlite.insert_memory(memory, entity_ids)
+                            memory.id = new_id
+                            self.memory_cache.put(memory)
+                            if mem_data.get("id"):
+                                memory_id_map[mem_data["id"]] = new_id
+
+                            batch_memories.append((new_id, memory.embedding_content()))
+                            imported += 1
+                            existing_hashes.add(content_hash)
+                        except Exception as e:
+                            errors.append(str(e))
+
+                    if batch_memories:
+                        try:
+                            texts = [text for _, text in batch_memories]
+                            embeddings = await self.embeddings.embed_batch_async(texts)
+                            for (mem_id, text), embedding in zip(batch_memories, embeddings):
+                                self.vectors.add(f"mem_{mem_id}", mem_id, text, embedding)
+                        except Exception as e:
+                            logger.warning(f"Batch embedding failed: {e}")
+                            for mem_id, text in batch_memories:
+                                try:
+                                    embedding = await self.embeddings.embed_async(text)
+                                    self.vectors.add(f"mem_{mem_id}", mem_id, text, embedding)
+                                except Exception:
+                                    pass
+
+                links_imported = 0
+                for link_data in links_data:
+                    old_source = link_data.get("source_memory_id")
+                    old_target = link_data.get("target_memory_id")
+                    new_source = memory_id_map.get(old_source)
+                    new_target = memory_id_map.get(old_target)
+
+                    if new_source and new_target:
+                        link = MemoryLink(
+                            source_memory_id=new_source,
+                            target_memory_id=new_target,
+                            link_type=LinkType(link_data["link_type"]),
+                            strength=link_data.get("strength", 0.5),
+                            reason=link_data.get("reason"),
+                        )
+                        if self.sqlite.insert_link(link):
+                            links_imported += 1
+
+                # Store completion as fact
+                result_memory = Memory(
+                    category=MemoryCategory.FACT,
+                    content=f"Import completed: {imported} memories, {skipped} skipped, {links_imported} links from {input_path}",
+                    what="Memory import completed",
+                    expires_at=datetime.now(UTC) + timedelta(days=1),
+                )
+                self.sqlite.insert_memory(result_memory)
+                logger.info(f"Import completed: {imported} memories from {input_path}")
+
+            except Exception as e:
+                logger.exception(f"Import failed: {e}")
+
+        task = asyncio.create_task(do_import())
+        task_id = _background_tasks.register("import_memories", task)
+
+        return {
+            "status": "queued",
+            "task_id": task_id,
+            "path": str(path),
+            "memories_count": len(memories_data),
+            "message": "Import running in background",
+            "hint": "Use recall('import completed') to check status",
+        }
+
+    def _bulk_archive(
+        self,
+        memory_ids: list[int] | None,
+        category: str | None,
+        older_than_days: int | None,
+        reason: str,
+    ) -> dict[str, Any]:
+        """Archive multiple memories at once."""
+        from datetime import timedelta
+
+        if not reason:
+            return {"error": "Reason is required for bulk archive"}
+
+        ids_to_archive: list[int] = []
+
+        # Collect IDs from explicit list
+        if memory_ids:
+            ids_to_archive.extend(memory_ids)
+
+        # Collect IDs from category + age filter
+        if category or older_than_days:
+            with self.sqlite._get_conn() as conn:
+                conditions = ["resolved_at IS NOT NULL"]  # Only archive resolved
+                params: list[Any] = []
+
+                if category:
+                    conditions.append("category = ?")
+                    params.append(category)
+
+                if older_than_days:
+                    cutoff = (datetime.now(UTC) - timedelta(days=older_than_days)).isoformat()
+                    conditions.append("created_at < ?")
+                    params.append(cutoff)
+
+                query = f"SELECT id FROM memories WHERE {' AND '.join(conditions)}"
+                cursor = conn.execute(query, params)
+                ids_to_archive.extend(row["id"] for row in cursor.fetchall())
+
+        # Deduplicate
+        ids_to_archive = list(set(ids_to_archive))
+
+        if not ids_to_archive:
+            return {"status": "no_matches", "archived_count": 0}
+
+        # Archive each memory
+        archived = 0
+        errors = []
+        for memory_id in ids_to_archive:
+            try:
+                if self.sqlite.archive_memory(memory_id, reason):
+                    archived += 1
+            except Exception as e:
+                errors.append(f"Failed to archive {memory_id}: {e}")
+
+        return {
+            "status": "archived",
+            "archived_count": archived,
+            "requested_count": len(ids_to_archive),
+            "errors": errors[:5] if errors else None,
+        }
+
+    async def _cache_cleanup_loop(self) -> None:
+        """Periodically clean expired cache entries."""
+        while True:
+            await asyncio.sleep(CACHE_CLEANUP_INTERVAL_SECONDS)
+            try:
+                removed = self.memory_cache.cleanup_expired()
+                if removed > 0:
+                    logger.debug(f"Cache cleanup: removed {removed} expired entries")
+            except Exception as e:
+                logger.warning(f"Cache cleanup error: {e}")
+
+    async def run(self) -> None:
+        """Run the MCP server."""
+        if self.daemon:
+            await self.daemon.start()
+
+        # Start cache cleanup background task
+        self._cache_cleanup_task = asyncio.create_task(self._cache_cleanup_loop())
+
+        try:
+            async with stdio_server() as (read_stream, write_stream):
+                await self.server.run(
+                    read_stream,
+                    write_stream,
+                    self.server.create_initialization_options(),
+                )
+        finally:
+            # Stop cache cleanup
+            if self._cache_cleanup_task:
+                self._cache_cleanup_task.cancel()
+                try:
+                    await self._cache_cleanup_task
+                except asyncio.CancelledError:
+                    pass
+
+            await self.enricher.close()
+            if self.daemon:
+                await self.daemon.stop()
+
+
+def main(enable_daemon: bool = True) -> None:
+    """Main entry point."""
+    server = MemoryServer(enable_daemon=enable_daemon)
+    asyncio.run(server.run())
+
+
+if __name__ == "__main__":
+    main()