deja-cli 0.1.0__py3-none-any.whl

deja/interfaces/cli.py

@@ -0,0 +1,1967 @@
+from __future__ import annotations
+
+import asyncio
+import gzip
+import json
+import shutil
+import stat
+import sys
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional, List
+
+import typer
+from ulid import ULID
+from watchdog.events import FileSystemEventHandler, FileSystemEvent
+from watchdog.observers import Observer
+
+from deja.config import load_config
+from deja.core.extractor import extract_memories
+from deja.core.store import MemoryStore
+from deja.ingest.watchers.claude_code import ClaudeCodeWatcher
+from deja.ingest.watchers.gemini_cli import GeminiCLIWatcher
+from deja.ingest.watchers.codex_cli import CodexCLIWatcher
+from deja.llm.embedding import EmbeddingAdapter
+from deja.llm.factory import create_adapter, create_embedding_adapter
+from deja.core.reflection import ReflectionEngine
+from deja.core.scheduler import make_scheduler
+
+app = typer.Typer(name="deja", help="Deja — persistent coding memory CLI")
+VALID_MERGE_STRATEGIES = {"skip", "overwrite", "update-confidence"}
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+
+def _get_config():
+    return load_config()
+
+
+def _get_store(config=None) -> MemoryStore:
+    if config is None:
+        config = _get_config()
+    return MemoryStore(config)
+
+
+async def _init_store(store: MemoryStore) -> None:
+    await store.init_db()
+
+
+async def _embed_and_save(
+    memories: list[dict],
+    store: MemoryStore,
+    embedding_adapter,  # Optional[EmbeddingAdapter]
+) -> int:
+    """Embed each memory (if adapter available) and save. Returns count saved."""
+    saved = 0
+    for memory in memories:
+        emb_bytes = None
+        if embedding_adapter is not None:
+            try:
+                emb = await embedding_adapter.embed(memory["content"])
+                emb_bytes = EmbeddingAdapter.to_bytes(emb)
+            except Exception as e:
+                print(f"[deja] Embedding failed: {e}", file=sys.stderr)
+        await store.save(memory, emb_bytes)
+        saved += 1
+    return saved
+
+
+def _format_memory_text(mem: dict) -> str:
+    scope = mem["scope"]
+    scope_label = "global" if scope == "global" else mem.get("project", scope)
+    domain = mem.get("domain")
+    domain_tag = f" [domain:{domain}]" if domain else ""
+    return (
+        f"[{mem['type']}]{domain_tag} [{scope_label}] {mem['content']} "
+        f"(confidence: {mem['confidence']:.1f})"
+    )
+
+
+def _format_load_result(result: dict) -> str:
+    """Render a load_budgeted() result as compact, agent-readable text."""
+    memories = result["memories"]
+    total = result["total"]
+    overflow = result["overflow"]
+    project = result["project"]
+    overflow_hints = result.get("overflow_hints", [])
+
+    if not memories and total == 0:
+        return "No memories found."
+
+    header = f"=== deja: {len(memories)}/{total} memories"
+    if project != "global":
+        header += f" (project: {project})"
+    header += " ==="
+
+    lines = [header]
+
+    by_type: dict[str, list[dict]] = {}
+    for mem in memories:
+        t = mem.get("type", "pattern")
+        by_type.setdefault(t, []).append(mem)
+
+    type_order = ["preference", "gotcha", "decision", "pattern", "procedure", "progress"]
+    for mem_type in type_order:
+        mems = by_type.get(mem_type, [])
+        if not mems:
+            continue
+        lines.append("")
+        for mem in mems:
+            label = f"[{mem_type}]"
+            if mem.get("domain"):
+                label += f"[{mem['domain']}]"
+            if mem_type == "procedure" and mem.get("reuse_count", 0):
+                label += f"(reuse:{mem['reuse_count']})"
+            if mem.get("scope") != "global":
+                label += f"({mem.get('project', '')})"
+            lines.append(f"{label} {mem['content']}")
+
+    if overflow > 0:
+        lines.append("")
+        search_cmd = 'deja search "<topic>"'
+        if project != "global":
+            search_cmd += f" --project {project}"
+        hints_str = ", ".join(f"{h['type']} +{h['overflow']}" for h in overflow_hints)
+        lines.append(f"--- {overflow} more memories available. Run: {search_cmd} ---")
+        if hints_str:
+            lines.append(f"Overflow: {hints_str}")
+
+    return "\n".join(lines)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _prepare_import_memory(raw: object, project: Optional[str]) -> tuple[Optional[dict], Optional[str]]:
+    """Validate and normalize one imported memory record."""
+    if not isinstance(raw, dict):
+        return None, "record is not a JSON object"
+
+    required_fields = ("id", "type", "content")
+    for field in required_fields:
+        value = raw.get(field)
+        if not isinstance(value, str) or not value.strip():
+            return None, f"missing required field: {field}"
+
+    scope = f"project:{project}" if project else raw.get("scope")
+    if not isinstance(scope, str) or not scope.strip():
+        return None, "missing required field: scope"
+
+    project_name = project if project else raw.get("project")
+    created_at = raw.get("created_at") or _now_iso()
+    updated_at = raw.get("updated_at") or created_at
+    last_confirmed = raw.get("last_confirmed") or updated_at
+
+    confidence = raw.get("confidence", 1.0)
+    try:
+        confidence = float(confidence)
+    except (TypeError, ValueError):
+        return None, "invalid confidence value"
+    confidence = max(0.0, min(1.0, confidence))
+
+    reuse_count = raw.get("reuse_count", 0)
+    try:
+        reuse_count = int(reuse_count)
+    except (TypeError, ValueError):
+        reuse_count = 0
+
+    normalized = {
+        "id": raw["id"],
+        "type": raw["type"],
+        "category": raw.get("category", "agent"),
+        "content": raw["content"],
+        "scope": scope,
+        "project": project_name,
+        "source": raw.get("source"),
+        "confidence": confidence,
+        "reuse_count": reuse_count,
+        "domain": raw.get("domain"),
+        "entity_graph": raw.get("entity_graph"),
+        "created_at": created_at,
+        "updated_at": updated_at,
+        "last_confirmed": last_confirmed,
+        "archived_at": raw.get("archived_at"),
+        "invalidated_at": raw.get("invalidated_at"),
+    }
+    return normalized, None
+
+
+# ── commands ──────────────────────────────────────────────────────────────────
+
+
+@app.command()
+def init():
+    """First-time setup: create ~/.deja/ directory structure."""
+    ms_dir = Path("~/.deja").expanduser()
+    store_dir = ms_dir / "store"
+    vault_dir = store_dir / "vault"
+    config_path = ms_dir / "config.yaml"
+
+    store_dir.mkdir(parents=True, exist_ok=True)
+    vault_dir.mkdir(parents=True, exist_ok=True)
+
+    if not config_path.exists():
+        default_config = Path(__file__).parent.parent.parent / "config" / "default.yaml"
+        if default_config.exists():
+            shutil.copy(default_config, config_path)
+            typer.echo(f"Created config at {config_path}")
+        else:
+            typer.echo(f"Warning: could not find default config to copy", err=True)
+    else:
+        typer.echo(f"Config already exists at {config_path}")
+
+    # Initialize the database
+    store = _get_store()
+    asyncio.run(_init_store(store))
+    asyncio.run(store.close())
+
+    typer.echo(f"Memory service initialized at {ms_dir}")
+
+
+@app.command()
+def load(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project name. Omit to load global memories only."),
+    format: str = typer.Option("text", "--format", "-f", help="Output format: json|text"),
+    context: Optional[str] = typer.Option(None, "--context", "-c", help="Task context query: re-ranks memories by relevance instead of raw confidence."),
+):
+    """Load memories as context for a session (type-slot budgeted).
+
+    With --project: returns global memories + that project's memories.
+    Without --project: returns global memories only.
+
+    Selects top-N per type (5 gotcha, 5 decision, 5 preference, 5 pattern,
+    3 procedure by reuse, 3 recent progress). Overflow count shown with search hint.
+
+    With --context: re-ranks within each type slot by relevance to the given query
+    (hybrid BM25 + embedding) instead of sorting by raw confidence.
+    """
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            embedding_adapter = await create_embedding_adapter(config) if context else None
+            return await store.load_budgeted(project, context=context, embedding_adapter=embedding_adapter)
+        finally:
+            await store.close()
+
+    result = asyncio.run(_run())
+
+    if format == "json":
+        typer.echo(json.dumps(result, indent=2, default=str))
+    else:
+        typer.echo(_format_load_result(result))
+
+
+@app.command()
+def save(
+    content: str = typer.Argument(..., help="Memory content to save"),
+    type: str = typer.Option("pattern", "--type", "-t", help="Memory type: preference|pattern|decision|gotcha|progress|procedure"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project name. Omit to save as global (cross-project)."),
+    confidence: float = typer.Option(1.0, "--confidence", "-c", help="Confidence score 0.0-1.0"),
+    category: str = typer.Option("agent", "--category", help="Category: user|agent"),
+    trigger: Optional[str] = typer.Option(None, "--trigger", help="Comma-separated phrases that activate this memory (e.g. 'kubectl apply, deploy k8s')."),
+):
+    """Save a memory directly (no LLM extraction).
+
+    Omit --project to save globally — the memory will appear in deja load for
+    every project. Use this for user preferences and broadly applicable patterns.
+
+    Use --project to scope the memory to a specific project — it only appears
+    in deja load --project <name>.
+
+    If embedding.provider is configured, generates an embedding automatically.
+    """
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+
+        embedding_bytes = None
+        embedding_adapter = await create_embedding_adapter(config)
+        if embedding_adapter is not None:
+            try:
+                emb = await embedding_adapter.embed(content)
+                embedding_bytes = EmbeddingAdapter.to_bytes(emb)
+            except Exception as e:
+                typer.echo(f"[deja] Embedding generation failed: {e}", err=True)
+
+        try:
+            scope = f"project:{project}" if project else "global"
+            memory = {
+                "type": type,
+                "category": category,
+                "content": content,
+                "scope": scope,
+                "project": project,
+                "source": "manual",
+                "confidence": confidence,
+                "trigger": trigger,
+            }
+            mem_id = await store.save(memory, embedding=embedding_bytes)
+            return mem_id
+        finally:
+            await store.close()
+
+    mem_id = asyncio.run(_run())
+    typer.echo(f"Saved memory: {mem_id}")
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search query"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Narrow to global + this project. Omit to search all scopes."),
+    type: Optional[str] = typer.Option(None, "--type", "-t", help="Filter by type"),
+    format: str = typer.Option("text", "--format", "-f", help="Output format: json|text"),
+):
+    """Search memories using hybrid BM25 + embedding search.
+
+    BM25 (keyword) always runs first. When BM25 returns fewer than 3 results
+    and embedding.provider is configured, semantic similarity search runs as
+    a fallback. Results are ranked by activation score (task_match, confidence,
+    recency, reuse_count). Enable semantic search in ~/.deja/config.yaml:
+      embedding:
+        provider: ollama
+        model: nomic-embed-text
+    Then run 'deja embed' to backfill embeddings for existing memories.
+    """
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        embedding_adapter = await create_embedding_adapter(config)
+        try:
+            results = await store.search(
+                query, project, mem_type=type, embedding_adapter=embedding_adapter
+            )
+            return results
+        finally:
+            await store.close()
+
+    results = asyncio.run(_run())
+
+    if format == "json":
+        typer.echo(json.dumps(results, indent=2, default=str))
+    else:
+        if not results:
+            typer.echo("No memories found.")
+            return
+        for mem in results:
+            typer.echo(_format_memory_text(mem))
+
+
+@app.command()
+def list(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Filter to global + this project. Omit to list everything."),
+    type: Optional[str] = typer.Option(None, "--type", "-t", help="Filter by type"),
+    format: str = typer.Option("text", "--format", "-f", help="Output format: json|text"),
+):
+    """List all active memories.
+
+    Without --project: shows every memory across all projects and global scope.
+    With --project: shows global + that project's memories only.
+    """
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            if project:
+                memories = await store.load(project)
+            else:
+                memories = await store.list_all()
+            if type:
+                memories = [m for m in memories if m["type"] == type]
+            return memories
+        finally:
+            await store.close()
+
+    memories = asyncio.run(_run())
+
+    if format == "json":
+        typer.echo(json.dumps(memories, indent=2, default=str))
+    else:
+        if not memories:
+            typer.echo("No memories found.")
+            return
+        for mem in memories:
+            typer.echo(_format_memory_text(mem))
+
+
+@app.command()
+def show(
+    memory_id: str = typer.Argument(..., help="Memory ID to show"),
+):
+    """Show details for a specific memory."""
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            return await store.get(memory_id)
+        finally:
+            await store.close()
+
+    mem = asyncio.run(_run())
+
+    if mem is None:
+        typer.echo(f"Memory {memory_id} not found.", err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(mem, indent=2, default=str))
+
+
+def _parse_transcript_for_path(path: Path, content: str) -> str:
+    """Auto-detect session file format from filename and convert to plain text.
+
+    Dispatches to the appropriate watcher's parse_transcript() based on filename:
+      session-*.json  → Gemini CLI JSON format
+      rollout-*.jsonl → Codex CLI JSONL format
+      anything else   → plain text (Claude Code summary.md, custom files)
+
+    This ensures deja save-session --transcript works correctly for all agents,
+    not just Claude Code's plain-text summary.md.
+    """
+    name = path.name
+    if name.startswith("session-") and name.endswith(".json"):
+        from deja.ingest.watchers.gemini_cli import GeminiCLIWatcher
+        return GeminiCLIWatcher.__new__(GeminiCLIWatcher).parse_transcript(content)
+    if name.startswith("rollout-") and name.endswith(".jsonl"):
+        from deja.ingest.watchers.codex_cli import CodexCLIWatcher
+        return CodexCLIWatcher.__new__(CodexCLIWatcher).parse_transcript(content)
+    return content
+
+
+@app.command(name="save-session")
+def save_session(
+    transcript: Optional[str] = typer.Option(None, "--transcript", "-t", help="Path to transcript file"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project name"),
+):
+    """Extract memories from a session transcript.
+
+    Without --transcript: prints an extraction prompt to stdout. The agent reads
+    it, identifies memories from the session, and calls deja save for each one.
+    This requires no API key — the agent already running IS the model.
+    Works identically for Claude Code, Gemini CLI, Codex, or any agent.
+
+    With --transcript: reads the file and uses the configured LLM to extract
+    memories automatically (requires extraction.provider set in config).
+    File format is auto-detected from the filename:
+      session-*.json  → Gemini CLI
+      rollout-*.jsonl → Codex CLI
+      anything else   → plain text (Claude Code summary.md)
+    """
+    from deja.core.extractor import EXTRACTION_SYSTEM
+
+    if transcript is None:
+        # Agent mode: print the prompt, let the agent do the extraction
+        project_hint = f" for project '{project}'" if project else ""
+        typer.echo(
+            f"Review this session's context{project_hint} and identify memories worth keeping.\n\n"
+            f"{EXTRACTION_SYSTEM}\n\n"
+            f"For each memory you identify, call:\n"
+            f"  deja save \"<content>\" --type <type>"
+            + (f" --project {project}" if project else "")
+            + "\n\n"
+            f"Only save things that are non-obvious, reusable, and important. "
+            f"If nothing is worth saving, do nothing."
+        )
+        return
+
+    async def _run():
+        config = _get_config()
+        adapter = await create_adapter(config, "extraction")
+        if adapter is None:
+            typer.echo(
+                "No LLM configured for extraction. Set extraction.provider in "
+                "~/.deja/config.yaml, or run `deja save-session` without "
+                "--transcript to let the agent extract memories interactively.",
+                err=True,
+            )
+            raise typer.Exit(1)
+
+        transcript_path = Path(transcript).expanduser()
+        if not transcript_path.exists():
+            typer.echo(f"Transcript file not found: {transcript_path}", err=True)
+            raise typer.Exit(1)
+
+        content = transcript_path.read_text(encoding="utf-8", errors="replace")
+        # Auto-detect format and convert to plain text before extraction.
+        # Without this, Gemini/Codex raw JSON files would confuse the extractor.
+        content = _parse_transcript_for_path(transcript_path, content)
+
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            from deja.core.extractor import extract_memories
+            memories = await extract_memories(
+                content, project or "unknown", "save-session", adapter
+            )
+            embedding_adapter = await create_embedding_adapter(config)
+            saved = await _embed_and_save(memories, store, embedding_adapter)
+            return saved
+        finally:
+            await store.close()
+
+    count = asyncio.run(_run())
+    typer.echo(f"Saved {count} memories from transcript.")
+
+
+@app.command(name="ingest-skills")
+def ingest_skills(
+    path: str = typer.Argument(..., help="Path to skill/rules file to import (markdown, plain text, .cursorrules, etc.)"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project name to scope imported memories to."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print what would be saved without writing to the store."),
+    no_llm: bool = typer.Option(False, "--no-llm", help="Skip LLM extraction. Parse markdown sections directly as procedure memories."),
+):
+    """Import an existing skill/rules file as procedure + pattern memories.
+
+    Accepts any plain-text file: markdown skill docs, .cursorrules, AGENTS.md,
+    custom rules files, etc.
+
+    LLM mode (default): passes the file through the extraction pipeline, same as
+    `deja save-session --transcript`. Requires extraction.provider set in config.
+    Infers types (procedure, pattern, gotcha) from content.
+
+    --no-llm mode: parses markdown ## headings as section boundaries. Each section
+    becomes one procedure memory (heading as title, body as content). Zero API cost.
+
+    --dry-run: prints what would be saved without touching the store.
+    """
+    skill_path = Path(path).expanduser()
+    if not skill_path.exists():
+        typer.echo(f"File not found: {skill_path}", err=True)
+        raise typer.Exit(1)
+
+    content = skill_path.read_text(encoding="utf-8", errors="replace")
+    if not content.strip():
+        typer.echo("File is empty.", err=True)
+        raise typer.Exit(1)
+
+    scope = f"project:{project}" if project else "global"
+
+    if no_llm:
+        # Heuristic markdown parser: split on ## headings, each section → procedure
+        memories = _parse_skills_markdown(content, project, scope)
+        if not memories:
+            typer.echo("No ## sections found. Use LLM mode or add markdown headings.", err=True)
+            raise typer.Exit(1)
+    else:
+        # LLM extraction mode
+        async def _extract():
+            config = _get_config()
+            adapter = await create_adapter(config, "extraction")
+            if adapter is None:
+                typer.echo(
+                    "No LLM configured for extraction. Set extraction.provider in "
+                    "~/.deja/config.yaml, or use --no-llm to parse markdown headings directly.",
+                    err=True,
+                )
+                raise typer.Exit(1)
+            from deja.core.extractor import extract_memories
+            return await extract_memories(content, project or "unknown", "ingest-skills", adapter)
+
+        memories = asyncio.run(_extract())
+        if not memories:
+            typer.echo("Extraction returned no memories. Try --no-llm or check the file format.", err=True)
+            raise typer.Exit(1)
+
+        # Force scope to match --project flag (extractor may infer differently)
+        if project:
+            for mem in memories:
+                mem["scope"] = scope
+                mem["project"] = project
+
+    if dry_run:
+        typer.echo(f"[dry-run] Would save {len(memories)} memories from {skill_path.name}:")
+        for mem in memories:
+            label = f"[{mem['type']}]"
+            if mem.get("project"):
+                label += f"({mem['project']})"
+            typer.echo(f"  {label} {mem['content'][:100]}")
+        return
+
+    async def _save():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            embedding_adapter = await create_embedding_adapter(config)
+            return await _embed_and_save(memories, store, embedding_adapter)
+        finally:
+            await store.close()
+
+    saved = asyncio.run(_save())
+    typer.echo(f"Saved {saved} memories from {skill_path.name}.")
+
+
+def _parse_skills_markdown(content: str, project: Optional[str], scope: str) -> list[dict]:
+    """Parse a markdown file into procedure memories by splitting on ## headings."""
+    import re
+    sections = re.split(r"^#{1,3} ", content, flags=re.MULTILINE)
+    memories = []
+    for section in sections:
+        section = section.strip()
+        if not section:
+            continue
+        lines = section.splitlines()
+        heading = lines[0].strip()
+        body = "\n".join(lines[1:]).strip()
+        if not heading:
+            continue
+        mem_content = f"{heading}: {body}" if body else heading
+        memories.append(
+            {
+                "type": "procedure",
+                "category": "agent",
+                "content": mem_content,
+                "scope": scope,
+                "project": project,
+                "source": "ingest-skills",
+                "confidence": 1.0,
+                "domain": None,
+            }
+        )
+    return memories
+
+
+@app.command()
+def export(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Export only this project's memories."),
+    type: Optional[str] = typer.Option(None, "--type", "-t", help="Comma-separated list of memory types to include."),
+    output: str = typer.Option("memories.jsonl", "--output", "-o", help="Output file path."),
+    compress: bool = typer.Option(False, "--compress", help="Compress output with gzip."),
+    include_archived: bool = typer.Option(False, "--include-archived", help="Include archived memories."),
+):
+    """Export memories to a JSONL file.
+
+    Format: JSONL (one memory per line).
+    Filters: --project, --type, --include-archived.
+    Compression: --compress (gzip).
+    """
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            types = type.split(",") if type else None
+            memories = await store.list_for_export(project, types, include_archived)
+            return memories
+        finally:
+            await store.close()
+
+    memories = asyncio.run(_run())
+
+    if not memories:
+        typer.echo("No memories found to export.")
+        return
+
+    output_path = Path(output)
+    if compress and not output_path.suffix == ".gz":
+        output_path = output_path.with_suffix(output_path.suffix + ".gz")
+
+    open_fn = gzip.open if compress or output_path.suffix == ".gz" else open
+    mode = "wt" if not (compress or output_path.suffix == ".gz") else "wb"
+
+    try:
+        with open_fn(output_path, mode) as f:
+            for mem in memories:
+                line = json.dumps(mem, default=str) + "\n"
+                if "b" in mode:
+                    f.write(line.encode("utf-8"))
+                else:
+                    f.write(line)
+        typer.echo(f"Exported {len(memories)} memories to {output_path}")
+    except Exception as e:
+        typer.echo(f"Export failed: {e}", err=True)
+        raise typer.Exit(1)
+
+
+@app.command(name="import")
+def import_cmd(
+    file: Path = typer.Argument(..., help="Path to the JSONL file to import."),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Overwrite scope and project for all imported memories."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview what would happen without modifying the database."),
+    merge_strategy: str = typer.Option("skip", "--merge-strategy", "-m", help="Strategy for handling ID collisions: skip|overwrite|update-confidence"),
+):
+    """Import memories from a JSONL file.
+
+    Format: JSONL or JSONL.gz (auto-detected).
+    Strategies: skip (default), overwrite, update-confidence.
+    """
+    if not file.exists():
+        typer.echo(f"Import file not found: {file}", err=True)
+        raise typer.Exit(1)
+    merge_strategy = merge_strategy.strip().lower()
+    if merge_strategy not in VALID_MERGE_STRATEGIES:
+        typer.echo(
+            f"Invalid merge strategy: {merge_strategy}. "
+            "Use one of: skip, overwrite, update-confidence",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+
+        stats = {
+            "inserted": 0,
+            "skipped": 0,
+            "updated": 0,
+            "overwritten": 0,
+            "invalid": 0,
+        }
+
+        try:
+            is_gz = file.suffix == ".gz"
+            open_fn = gzip.open if is_gz else open
+            mode = "rt" if not is_gz else "rb"
+
+            with open_fn(file, mode) as f:
+                for line_no, line_bytes in enumerate(f, start=1):
+                    line = line_bytes.decode("utf-8") if is_gz else line_bytes
+                    if not line.strip():
+                        continue
+
+                    try:
+                        raw_memory = json.loads(line)
+                    except json.JSONDecodeError:
+                        typer.echo(
+                            f"Warning: skipped malformed line {line_no} in {file}",
+                            err=True,
+                        )
+                        stats["invalid"] += 1
+                        continue
+
+                    memory, validation_error = _prepare_import_memory(raw_memory, project)
+                    if validation_error:
+                        typer.echo(
+                            f"Warning: skipped invalid line {line_no} in {file}: {validation_error}",
+                            err=True,
+                        )
+                        stats["invalid"] += 1
+                        continue
+
+                    existing = await store.get(memory["id"])
+                    if project and existing:
+                        target_scope = f"project:{project}"
+                        existing_scope = existing.get("scope")
+                        existing_project = existing.get("project")
+                        if existing_scope != target_scope or existing_project != project:
+                            memory["id"] = str(ULID())
+                            existing = None
+
+                    if dry_run:
+                        if not existing:
+                            stats["inserted"] += 1
+                        elif merge_strategy == "skip":
+                            stats["skipped"] += 1
+                        elif merge_strategy == "overwrite":
+                            stats["overwritten"] += 1
+                        elif merge_strategy == "update-confidence":
+                            if memory["content"] == existing["content"]:
+                                stats["updated"] += 1
+                            else:
+                                stats["skipped"] += 1
+                    else:
+                        result = await store.upsert(memory, merge_strategy)
+                        stats[result] += 1
+
+            return stats
+        finally:
+            await store.close()
+
+    stats = asyncio.run(_run())
+
+    action = "Would import" if dry_run else "Imported"
+    total = stats["inserted"] + stats["skipped"] + stats["updated"] + stats["overwritten"]
+    typer.echo(f"{action}: {total} memories")
+    if stats["inserted"]:
+        typer.echo(f"  - {stats['inserted']} new ({'would insert' if dry_run else 'inserted'})")
+    if stats["skipped"]:
+        typer.echo(f"  - {stats['skipped']} already exist ({'would skip' if dry_run else 'skipped'})")
+    if stats["updated"]:
+        typer.echo(f"  - {stats['updated']} confidence bumped ({'would update' if dry_run else 'updated'})")
+    if stats["overwritten"]:
+        typer.echo(f"  - {stats['overwritten']} records replaced ({'would overwrite' if dry_run else 'overwritten'})")
+    if stats["invalid"]:
+        typer.echo(f"  - {stats['invalid']} invalid records ({'would skip' if dry_run else 'skipped'})")
+
+
+@app.command()
+def update(
+    memory_id: str = typer.Argument(..., help="Memory ID to update"),
+    trigger: Optional[str] = typer.Option(None, "--trigger", help="Comma-separated trigger phrases to add (merged with existing)."),
+    type: Optional[str] = typer.Option(None, "--type", "-t", help="New memory type: preference|pattern|decision|gotcha|progress|procedure"),
+):
+    """Update metadata on an existing memory.
+
+    Only trigger and type can be updated. Content changes should use
+    deja save (which deduplicates automatically).
+
+    Trigger phrases are merged with any existing trigger, not replaced.
+
+    Example:
+      deja update 01JKB... --trigger "kubectl apply, helm upgrade"
+      deja update 01JKB... --type gotcha
+    """
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            fields = {}
+            if trigger is not None:
+                fields["trigger"] = trigger
+            if type is not None:
+                fields["type"] = type
+            if not fields:
+                typer.echo("No fields to update. Use --trigger or --type.", err=True)
+                raise typer.Exit(1)
+            updated = await store.update_memory(memory_id, fields)
+            return updated
+        finally:
+            await store.close()
+
+    updated = asyncio.run(_run())
+    if updated:
+        typer.echo(f"Updated memory: {memory_id}")
+    else:
+        typer.echo(f"Memory not found or already archived: {memory_id}", err=True)
+        raise typer.Exit(1)
+
+
+@app.command()
+def archive(
+    memory_id: str = typer.Argument(..., help="Memory ID to archive"),
+):
+    """Archive a memory (soft delete)."""
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            await store.archive(memory_id)
+        finally:
+            await store.close()
+
+    asyncio.run(_run())
+    typer.echo(f"Archived memory: {memory_id}")
+
+
+@app.command()
+def reflect(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project to reflect on."),
+    agent_mode: bool = typer.Option(
+        False, "--agent-mode", "-a",
+        help="Print memory dump + instructions for the coding agent to reflect. No LLM call.",
+    ),
+):
+    """Reflect on memories: compress (Observer/Reflector), decay, promote, archive.
+
+    Two modes:
+
+    Agent mode (--agent-mode): prints a memory dump with instructions for the active
+    coding agent (Claude Code, Codex, Gemini CLI) to execute deja commands directly.
+    Zero extra API cost — the agent is already being billed for the session.
+
+    LLM mode (default): uses the configured reflection LLM (Ollama/Anthropic) to run
+    the Observer and Reflector passes, then decay/promote/archive without LLM.
+    """
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            if agent_mode:
+                engine = ReflectionEngine(store, config.reflection)
+                return "agent_mode", await engine.agent_mode_prompt(project)
+            adapter = await create_adapter(config, "reflection")
+            if not adapter:
+                return "no_llm", None
+            engine = ReflectionEngine(store, config.reflection, adapter)
+            return "done", await engine.run_full(project)
+        finally:
+            await store.close()
+
+    result_type, data = asyncio.run(_run())
+
+    if result_type == "agent_mode":
+        typer.echo(data)
+    elif result_type == "no_llm":
+        typer.echo(
+            "No reflection LLM configured. Options:\n"
+            "  --agent-mode          use the active coding agent as reflector (free)\n"
+            "  deja config set reflection.provider anthropic  (or ollama)",
+            err=True,
+        )
+        raise typer.Exit(1)
+    else:
+        results = data
+        lines = ["Reflection complete:"]
+        if results.get("observer"):
+            lines.append(f"  Observer:  {results['observer']} observations created")
+        if results.get("reflector"):
+            lines.append(f"  Reflector: {results['reflector']} observations condensed")
+        if results.get("decay"):
+            lines.append(f"  Decay:     {results['decay']} memories decayed")
+        if results.get("promote"):
+            lines.append(f"  Promote:   {results['promote']} patterns promoted to global")
+        if results.get("archive"):
+            lines.append(f"  Archive:   {results['archive']} memories archived")
+        if len(lines) == 1:
+            lines.append("  Nothing to do.")
+        typer.echo("\n".join(lines))
+
+
+@app.command()
+def stats(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project to show stats for."),
+):
+    """Show memory vault statistics: counts by type, token estimate, last reflection times."""
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            return await store.get_stats(project)
+        finally:
+            await store.close()
+
+    s = asyncio.run(_run())
+
+    typer.echo(f"Project:        {s['project']}")
+    typer.echo(f"Active:         {s['active']}")
+    for t, cnt in sorted(s["by_type"].items()):
+        typer.echo(f"  {t:<16} {cnt}")
+    typer.echo(f"Archived:       {s['archived']}")
+    typer.echo(f"Invalidated:    {s['invalidated']}")
+    typer.echo(f"Observations:   {s['observations']}")
+    typer.echo(f"Token estimate: ~{s['token_estimate']}")
+    if s["last_observer_at"]:
+        typer.echo(f"Last observer:  {s['last_observer_at'][:19]}")
+    if s["last_reflector_at"]:
+        typer.echo(f"Last reflector: {s['last_reflector_at'][:19]}")
+    if s["last_decay_at"]:
+        typer.echo(f"Last decay:     {s['last_decay_at'][:19]}")
+    typer.echo(f"With embeddings: {s.get('with_embeddings', 0)}/{s['active']}")
+
+
+@app.command()
+def embed(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Scope backfill to global + this project. Omit to backfill all."),
+):
+    """Generate embeddings for memories that don't have one yet.
+
+    Run this after enabling embedding.provider in ~/.deja/config.yaml to
+    backfill embeddings for memories saved before semantic search was configured.
+
+    Requires:
+      1. embedding.provider set to 'ollama' in ~/.deja/config.yaml
+      2. Ollama running with the configured model pulled:
+           ollama pull nomic-embed-text
+    """
+    async def _run():
+        config = _get_config()
+        embedding_adapter = await create_embedding_adapter(config)
+        if embedding_adapter is None:
+            typer.echo(
+                "No embedding provider configured.\n"
+                "Set embedding.provider in ~/.deja/config.yaml, e.g.:\n"
+                "  embedding:\n"
+                "    provider: ollama\n"
+                "    model: nomic-embed-text",
+                err=True,
+            )
+            return 0, 0
+
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            memories = await store.get_memories_without_embeddings(project)
+            done = 0
+            failed = 0
+            for mem in memories:
+                try:
+                    emb = await embedding_adapter.embed(mem["content"])
+                    emb_bytes = EmbeddingAdapter.to_bytes(emb)
+                    await store.save_embedding(mem["id"], emb_bytes)
+                    done += 1
+                except Exception as e:
+                    typer.echo(f"[deja] Failed to embed {mem['id']}: {e}", err=True)
+                    failed += 1
+            return done, failed
+        finally:
+            await store.close()
+
+    done, failed = asyncio.run(_run())
+    typer.echo(f"Embedded {done} memories." + (f" {failed} failed." if failed else ""))
+
+
+@app.command()
+def invalidate(
+    memory_id: str = typer.Argument(..., help="Memory ID to mark as superseded."),
+):
+    """Mark a memory as invalidated (superseded by newer information).
+
+    Unlike archive (soft-delete for low-confidence memories), invalidate signals that
+    this memory has been actively contradicted — used in agent-mode reflection when
+    the agent identifies a memory that is no longer correct.
+    """
+    async def _run():
+        config = _get_config()
+        store = _get_store(config)
+        await store.init_db()
+        try:
+            await store.invalidate(memory_id)
+        finally:
+            await store.close()
+
+    asyncio.run(_run())
+    typer.echo(f"Invalidated: {memory_id}")
+
+
+# ── backfill helpers ──────────────────────────────────────────────────────────
+
+
+def _get_project_name_from_dir(project_dir: Path) -> str:
+    """Resolve a human-readable project name from a ~/.claude/projects/<hash> dir.
+
+    Priority:
+    1. sessions-index.json → entries[0].projectPath → basename
+    2. First .jsonl file → cwd field → basename
+    3. Reconstruct from dir name (/ → - encoding); check if path exists on disk
+    4. Last hyphen-delimited token of dir name
+    """
+    index_file = project_dir / "sessions-index.json"
+    if index_file.exists():
+        try:
+            data = json.loads(index_file.read_text(encoding="utf-8"))
+            for entry in data.get("entries", []):
+                pp = entry.get("projectPath")
+                if pp:
+                    return Path(pp).name
+        except Exception:
+            pass
+
+    for jsonl_file in sorted(project_dir.glob("*.jsonl")):
+        try:
+            for raw in jsonl_file.read_text(encoding="utf-8", errors="replace").splitlines():
+                d = json.loads(raw)
+                cwd = d.get("cwd")
+                if cwd:
+                    return Path(cwd).name
+        except Exception:
+            continue
+
+    raw = project_dir.name
+    reconstructed = Path("/" + raw.lstrip("-").replace("-", "/"))
+    if reconstructed.exists():
+        return reconstructed.name
+    return raw.split("-")[-1] or raw
+
+
+def _sessions_index_transcript(index_path: Path) -> str:
+    """Build a lightweight transcript from sessions-index.json per-session metadata."""
+    try:
+        data = json.loads(index_path.read_text(encoding="utf-8"))
+        parts = []
+        for entry in data.get("entries", []):
+            summary = (entry.get("summary") or "").strip()
+            first_prompt = (entry.get("firstPrompt") or "").strip()
+            if summary or first_prompt:
+                parts.append(f"Session summary: {summary}\nUser's first message: {first_prompt}")
+        return "\n\n---\n\n".join(parts)
+    except Exception:
+        return ""
+
+
+def _parse_jsonl_transcript(jsonl_path: Path, max_chars: int = 30_000) -> str:
+    """Extract a readable transcript from a Claude Code .jsonl session file.
+
+    Keeps user messages and assistant text blocks; skips thinking blocks and
+    tool results to keep the text focused.
+    """
+    turns = []
+    try:
+        for raw in jsonl_path.read_text(encoding="utf-8", errors="replace").splitlines():
+            try:
+                d = json.loads(raw)
+            except json.JSONDecodeError:
+                continue
+
+            if d.get("type") not in ("user", "assistant"):
+                continue
+
+            msg = d.get("message", {})
+            role = msg.get("role", d["type"])
+            content = msg.get("content", "")
+
+            if isinstance(content, str):
+                text = content.strip()
+            elif isinstance(content, type([])):  # list — avoid name shadowed by `def list()`
+                parts = [
+                    item.get("text", "").strip()
+                    for item in content
+                    if isinstance(item, dict) and item.get("type") == "text"
+                ]
+                text = "\n".join(p for p in parts if p)
+            else:
+                continue
+
+            if text:
+                turns.append(f"{role.capitalize()}: {text}")
+    except Exception:
+        return ""
+
+    full = "\n\n".join(turns)
+    return full[:max_chars]
+
+
+@app.command()
+def backfill(
+    project: Optional[str] = typer.Option(
+        None, "--project", "-p",
+        help="Only backfill this project. Omit to backfill all projects."
+    ),
+    include_sessions: Optional[bool] = typer.Option(
+        None, "--include-sessions/--no-include-sessions", "-s/-S",
+        help="Process full .jsonl session transcripts. Defaults to True in --agent-mode, False otherwise."
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run",
+        help="Show what would be processed without calling the LLM or saving."
+    ),
+    agent_mode: bool = typer.Option(
+        False, "--agent-mode",
+        help=(
+            "Print session content + instructions for the active agent to extract memories. "
+            "No LLM API call needed — the agent running IS the model. "
+            "Defaults --include-sessions to True."
+        ),
+    ),
+    claude_dir: str = typer.Option(
+        "~/.claude/projects",
+        "--claude-dir",
+        help="Path to the Claude projects directory.",
+    ),
+):
+    """Backfill memories from existing Claude Code session history.
+
+    Processes for each project (in order):
+      1. session-memory/summary.md files (structured session summaries)
+      2. sessions-index.json per-session summaries (lightweight, one LLM call per project)
+      3. Full .jsonl session transcripts (with --include-sessions or --agent-mode)
+
+    --agent-mode: prints all session content to stdout with deja save instructions.
+    The active coding agent reads the output and calls deja save for each memory.
+    No API key required — the agent already running is the LLM.
+
+    Deduplication is handled automatically — re-running backfill is safe.
+    Without --agent-mode, requires extraction.provider set in ~/.deja/config.yaml.
+    """
+    # In agent mode, include full session transcripts by default (richer signal).
+    # User can explicitly override with --no-include-sessions.
+    effective_include_sessions = include_sessions if include_sessions is not None else agent_mode
+
+    projects_root = Path(claude_dir).expanduser()
+    if not projects_root.exists():
+        typer.echo(f"Claude projects directory not found: {projects_root}", err=True)
+        raise typer.Exit(1)
+
+    # ── Agent mode: dump content + instructions, no LLM call ─────────────────
+    if agent_mode:
+        from deja.core.extractor import EXTRACTION_SYSTEM
+
+        project_dirs = sorted(p for p in projects_root.iterdir() if p.is_dir())
+        total_sources = 0
+
+        for project_dir in project_dirs:
+            proj_name = _get_project_name_from_dir(project_dir)
+
+            if project and proj_name != project:
+                continue
+
+            typer.echo(f"\n{'='*60}")
+            typer.echo(f"=== Backfill: {proj_name} ===")
+            typer.echo(f"{'='*60}\n")
+
+            # 1. summary.md files
+            for summary_file in sorted(project_dir.rglob("session-memory/summary.md")):
+                content = summary_file.read_text(encoding="utf-8", errors="replace").strip()
+                if not content:
+                    continue
+                total_sources += 1
+                typer.echo(f"--- summary.md ---")
+                typer.echo(content)
+                typer.echo()
+
+            # 2. sessions-index.json
+            index_file = project_dir / "sessions-index.json"
+            if index_file.exists():
+                transcript = _sessions_index_transcript(index_file)
+                if transcript.strip():
+                    try:
+                        entry_count = len(json.loads(index_file.read_text()).get("entries", []))
+                    except Exception:
+                        entry_count = "?"
+                    total_sources += 1
+                    typer.echo(f"--- sessions-index.json ({entry_count} sessions) ---")
+                    typer.echo(transcript)
+                    typer.echo()
+
+            # 3. full .jsonl session transcripts
+            if effective_include_sessions:
+                jsonl_files = sorted(
+                    f for f in project_dir.glob("*.jsonl")
+                    if f.parent.name != "subagents"
+                )
+                for jsonl_file in jsonl_files:
+                    transcript = _parse_jsonl_transcript(jsonl_file)
+                    if not transcript.strip():
+                        continue
+                    total_sources += 1
+                    typer.echo(f"--- {jsonl_file.name} ---")
+                    typer.echo(transcript)
+                    typer.echo()
+
+        if total_sources == 0:
+            typer.echo("No session content found to process.")
+            return
+
+        project_flag = f" --project {project}" if project else ""
+        typer.echo(f"\n{'='*60}")
+        typer.echo("=== Instructions ===")
+        typer.echo(f"{'='*60}")
+        typer.echo(
+            f"\nReview all session content above and identify memories worth keeping.\n\n"
+            f"{EXTRACTION_SYSTEM}\n\n"
+            f"For each memory you identify, call:\n"
+            f"  deja save \"<content>\" --type <type>{project_flag}\n"
+            f"  (omit --project for global memories that apply across all projects)\n\n"
+            f"Only save things that are non-obvious, reusable, and important.\n"
+            f"If nothing is worth saving, do nothing.\n"
+            f"\n({total_sources} sources printed above)"
+        )
+        return
+
+    # ── Auto mode: use configured LLM ────────────────────────────────────────
+    async def _run():
+        config = _get_config()
+        if dry_run:
+            adapter = None
+        else:
+            adapter = await create_adapter(config, "extraction")
+            if adapter is None:
+                typer.echo(
+                    "No LLM configured for extraction. Set extraction.provider in "
+                    "~/.deja/config.yaml, or use --agent-mode to let the "
+                    "active coding agent extract memories without an API call.",
+                    err=True,
+                )
+                raise typer.Exit(1)
+
+        store = _get_store(config)
+        await store.init_db()
+        embedding_adapter = await create_embedding_adapter(config)
+
+        total_sources = 0
+        total_memories = 0
+
+        try:
+            project_dirs = sorted(p for p in projects_root.iterdir() if p.is_dir())
+
+            for project_dir in project_dirs:
+                proj_name = _get_project_name_from_dir(project_dir)
+
+                if project and proj_name != project:
+                    continue
+
+                typer.echo(f"\nProject: {proj_name}  ({project_dir.name})")
+
+                # ── 1. summary.md files ──────────────────────────────────────
+                for summary_file in sorted(project_dir.rglob("session-memory/summary.md")):
+                    total_sources += 1
+                    content = summary_file.read_text(encoding="utf-8", errors="replace").strip()
+                    if not content:
+                        typer.echo(f"  summary.md  (empty, skipped)")
+                        continue
+
+                    if dry_run:
+                        typer.echo(f"  [dry-run] summary.md  ({len(content)} chars)")
+                        continue
+
+                    memories = await extract_memories(content, proj_name, "backfill", adapter)
+                    total_memories += await _embed_and_save(memories, store, embedding_adapter)
+                    typer.echo(f"  summary.md  → {len(memories)} memories")
+
+                # ── 2. sessions-index.json ───────────────────────────────────
+                index_file = project_dir / "sessions-index.json"
+                if index_file.exists():
+                    total_sources += 1
+                    transcript = _sessions_index_transcript(index_file)
+                    if not transcript.strip():
+                        typer.echo(f"  sessions-index.json  (no summaries, skipped)")
+                    elif dry_run:
+                        entry_count = len(json.loads(index_file.read_text()).get("entries", []))
+                        typer.echo(f"  [dry-run] sessions-index.json  ({entry_count} sessions)")
+                    else:
+                        entry_count = len(json.loads(index_file.read_text()).get("entries", []))
+                        memories = await extract_memories(transcript, proj_name, "backfill", adapter)
+                        total_memories += await _embed_and_save(memories, store, embedding_adapter)
+                        typer.echo(f"  sessions-index.json  ({entry_count} sessions) → {len(memories)} memories")
+
+                # ── 3. full .jsonl transcripts (opt-in) ──────────────────────
+                if effective_include_sessions:
+                    jsonl_files = sorted(
+                        f for f in project_dir.glob("*.jsonl")
+                        if f.parent.name != "subagents"
+                    )
+                    for jsonl_file in jsonl_files:
+                        total_sources += 1
+                        transcript = _parse_jsonl_transcript(jsonl_file)
+                        if not transcript.strip():
+                            continue
+
+                        if dry_run:
+                            typer.echo(f"  [dry-run] {jsonl_file.name}  ({len(transcript)} chars)")
+                            continue
+
+                        memories = await extract_memories(transcript, proj_name, "backfill", adapter)
+                        total_memories += await _embed_and_save(memories, store, embedding_adapter)
+                        typer.echo(f"  {jsonl_file.name}  → {len(memories)} memories")
+
+        finally:
+            await store.close()
+
+        return total_sources, total_memories
+
+    total_sources, total_memories = asyncio.run(_run())
+    typer.echo(f"\nDone. {total_sources} sources processed, {total_memories} memories saved.")
+
+
+@app.command()
+def viewer(
+    host: str = typer.Option("127.0.0.1", "--host", help="Host to bind to."),
+    port: int = typer.Option(8888, "--port", "-p", help="Port to listen on."),
+    no_browser: bool = typer.Option(False, "--no-browser", help="Don't open browser automatically."),
+):
+    """Launch the deja web viewer.
+
+    Opens a browser UI to browse, search, and manage your memory vault.
+    Press Ctrl+C to stop.
+    """
+    try:
+        import uvicorn
+    except ImportError:
+        typer.echo("uvicorn not installed. Run: uv add uvicorn", err=True)
+        raise typer.Exit(1)
+
+    from deja.interfaces.web import app as web_app
+
+    if not no_browser:
+        import threading
+        import webbrowser
+        import time
+
+        def _open():
+            time.sleep(0.8)
+            webbrowser.open(f"http://{host}:{port}")
+
+        threading.Thread(target=_open, daemon=True).start()
+
+    typer.echo(f"deja viewer → http://{host}:{port}  (Ctrl+C to stop)")
+    uvicorn.run(web_app, host=host, port=port, log_level="warning")
+
+
+@app.command()
+def watch():
+    """Start watching for session files from enabled agents.
+
+    Agents watched (configured in ~/.deja/config.yaml):
+      claude_code: ~/.claude/projects/**/session-memory/summary.md
+      gemini_cli:  ~/.gemini/tmp/**/chats/session-*.json
+      codex_cli:   ~/.codex/sessions/**/rollout-*.jsonl
+
+    Enable additional watchers by setting them to true in config:
+      watchers:
+        gemini_cli: true
+        codex_cli: true
+    """
+    config = _get_config()
+    store = _get_store(config)
+
+    # Run event loop in background thread for async operations
+    loop = asyncio.new_event_loop()
+
+    def start_loop():
+        asyncio.set_event_loop(loop)
+        loop.run_forever()
+
+    loop_thread = threading.Thread(target=start_loop, daemon=True)
+    loop_thread.start()
+
+    # Initialize store in the background loop
+    future = asyncio.run_coroutine_threadsafe(store.init_db(), loop)
+    future.result(timeout=10)
+
+    # Create adapter (may be None if provider: none — watcher saves raw summaries)
+    adapter_future = asyncio.run_coroutine_threadsafe(
+        create_adapter(config, "extraction"), loop
+    )
+    adapter = adapter_future.result(timeout=10)
+    if adapter is None:
+        typer.echo(
+            "Note: no LLM configured. Watcher will save raw session summaries as "
+            "progress memories. Set extraction.provider in ~/.deja/config.yaml "
+            "to enable structured extraction."
+        )
+
+    embedding_adapter_future = asyncio.run_coroutine_threadsafe(
+        create_embedding_adapter(config), loop
+    )
+    embedding_adapter = embedding_adapter_future.result(timeout=10)
+
+    # Create reflection engine + scheduler
+    reflection_adapter_future = asyncio.run_coroutine_threadsafe(
+        create_adapter(config, "reflection"), loop
+    )
+    reflection_adapter = reflection_adapter_future.result(timeout=10)
+    engine = ReflectionEngine(store, config.reflection, reflection_adapter)
+    scheduler = make_scheduler(engine, loop)
+    scheduler.start()
+    typer.echo("Reflection scheduler started (nightly 2am + 5-min token-count checks).")
+
+    # Build the list of enabled watchers
+    watcher_kwargs = dict(
+        store=store,
+        extractor_fn=extract_memories,
+        adapter=adapter,
+        debounce_seconds=config.watchers.debounce_seconds,
+        embedding_adapter=embedding_adapter,
+    )
+    watchers = []
+    if config.watchers.claude_code:
+        watchers.append(ClaudeCodeWatcher(**watcher_kwargs))
+    if config.watchers.gemini_cli:
+        watchers.append(GeminiCLIWatcher(**watcher_kwargs))
+    if config.watchers.codex_cli:
+        watchers.append(CodexCLIWatcher(**watcher_kwargs))
+
+    if not watchers:
+        typer.echo(
+            "No watchers enabled. Set at least one to true in ~/.deja/config.yaml:\n"
+            "  watchers:\n"
+            "    claude_code: true\n"
+            "    gemini_cli: true\n"
+            "    codex_cli: true",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    observer = Observer()
+
+    for watcher in watchers:
+        # Each watcher gets its own handler that calls its handle_file_event
+        class _Handler(FileSystemEventHandler):
+            def __init__(self, w):
+                self._watcher = w
+
+            def on_modified(self, event: FileSystemEvent):
+                if not event.is_directory:
+                    path = Path(event.src_path)
+                    loop.call_soon_threadsafe(self._watcher.handle_file_event, path)
+
+            def on_created(self, event: FileSystemEvent):
+                if not event.is_directory:
+                    path = Path(event.src_path)
+                    loop.call_soon_threadsafe(self._watcher.handle_file_event, path)
+
+        handler = _Handler(watcher)
+        for watch_path in watcher.get_watch_paths():
+            watch_path.mkdir(parents=True, exist_ok=True)
+            observer.schedule(handler, str(watch_path), recursive=True)
+            typer.echo(f"Watching [{watcher.__class__.__name__}]: {watch_path}")
+
+    observer.start()
+    typer.echo("Memory service watcher running. Press Ctrl+C to stop.")
+
+    stop_event = threading.Event()
+    try:
+        stop_event.wait()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        scheduler.shutdown(wait=False)
+        observer.stop()
+        observer.join()
+        loop.call_soon_threadsafe(loop.stop)
+        asyncio.run_coroutine_threadsafe(store.close(), loop)
+        typer.echo("\nWatcher stopped.")
+
+
+# ── setup command ─────────────────────────────────────────────────────────────
+
+# Hook scripts are embedded here so `deja setup` works after `uv tool install`
+# without the source repo present.
+
+_RECALL_HOOK_SCRIPT = r"""#!/usr/bin/env bash
+# deja-recall.sh — pre-tool-use hook for Claude Code
+#
+# Fires before each Bash tool call. Classifies the command against a short
+# allowlist of high-signal operations (deploy, migrate, rotate, etc.), runs
+# `deja search` for matching ones, and injects relevant gotchas/procedures
+# into the agent's context before the command executes.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+CMD=$(echo "$INPUT"       | jq -r '.tool_input.command // ""')
+
+# Only fire for Bash tool calls
+[ "$TOOL_NAME" != "Bash" ] && exit 0
+
+INTENT=""
+
+if echo "$CMD" | grep -qE "kubectl apply|helm upgrade|kubectl rollout"; then
+  INTENT="deploy kubernetes"
+elif echo "$CMD" | grep -qE "alembic upgrade|alembic downgrade|flask db upgrade|python manage.py migrate"; then
+  INTENT="database migration"
+elif echo "$CMD" | grep -qE "terraform apply|terraform destroy|terraform import"; then
+  INTENT="terraform infrastructure"
+elif echo "$CMD" | grep -qE "git push.*(--force|-f)|git push.*(main|master)"; then
+  INTENT="git push force main"
+elif echo "$CMD" | grep -qE "aws.*deploy|aws.*update|aws.*delete|aws.*terminate"; then
+  INTENT="aws deploy infrastructure"
+elif echo "$CMD" | grep -qE "secret|credential|rotate|revoke|vault"; then
+  INTENT="secret rotation credentials"
+elif echo "$CMD" | grep -qE "docker.*push|docker.*deploy|docker.*prod"; then
+  INTENT="docker deploy production"
+elif echo "$CMD" | grep -qE "pg_dump|mysqldump|mongodump|pg_restore|mongorestore"; then
+  INTENT="database backup restore"
+elif echo "$CMD" | grep -qE "npm publish|pip publish|cargo publish|gem push"; then
+  INTENT="publish package release"
+fi
+
+[ -z "$INTENT" ] && exit 0
+
+MEMORIES=$(deja search "$INTENT" 2>/dev/null || true)
+
+[ -z "$MEMORIES" ] && exit 0
+
+jq -n --arg ctx "$MEMORIES" '{
+  "hookSpecificOutput": {
+    "additionalContext": ("[deja recall]\n" + $ctx)
+  }
+}'
+"""
+
+_POST_FAIL_HOOK_SCRIPT = r"""#!/usr/bin/env bash
+# deja-post-fail.sh — post-tool-use hook for Claude Code
+#
+# Fires after each Bash tool call. If the command was high-signal AND failed
+# (non-zero exit / is_error), searches deja for related gotchas and injects
+# them so the agent debugs with past context immediately.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+CMD=$(echo "$INPUT"       | jq -r '.tool_input.command // ""')
+
+[ "$TOOL_NAME" != "Bash" ] && exit 0
+
+EXIT_CODE=$(echo "$INPUT" | jq -r '.tool_result.exit_code // 0')
+IS_ERROR=$(echo "$INPUT"  | jq -r '.tool_result.is_error // false')
+
+if [ "$EXIT_CODE" = "0" ] && [ "$IS_ERROR" = "false" ]; then
+  exit 0
+fi
+
+INTENT=""
+
+if echo "$CMD" | grep -qE "kubectl apply|helm upgrade|kubectl rollout"; then
+  INTENT="deploy kubernetes"
+elif echo "$CMD" | grep -qE "alembic upgrade|alembic downgrade|flask db upgrade|python manage.py migrate"; then
+  INTENT="database migration"
+elif echo "$CMD" | grep -qE "terraform apply|terraform destroy|terraform import"; then
+  INTENT="terraform infrastructure"
+elif echo "$CMD" | grep -qE "git push.*(--force|-f)|git push.*(main|master)"; then
+  INTENT="git push force main"
+elif echo "$CMD" | grep -qE "aws.*deploy|aws.*update|aws.*delete|aws.*terminate"; then
+  INTENT="aws deploy infrastructure"
+elif echo "$CMD" | grep -qE "secret|credential|rotate|revoke|vault"; then
+  INTENT="secret rotation credentials"
+elif echo "$CMD" | grep -qE "docker.*push|docker.*deploy|docker.*prod"; then
+  INTENT="docker deploy production"
+elif echo "$CMD" | grep -qE "pg_dump|mysqldump|mongodump|pg_restore|mongorestore"; then
+  INTENT="database backup restore"
+elif echo "$CMD" | grep -qE "npm publish|pip publish|cargo publish|gem push"; then
+  INTENT="publish package release"
+fi
+
+[ -z "$INTENT" ] && exit 0
+
+MEMORIES=$(deja search "$INTENT" 2>/dev/null || true)
+
+[ -z "$MEMORIES" ] && exit 0
+
+jq -n --arg ctx "$MEMORIES" '{
+  "systemMessage": ("[deja recall — command failed, related gotchas]\n" + $ctx)
+}'
+"""
+
+_SESSION_END_HOOK_SCRIPT = r"""#!/usr/bin/env bash
+# deja-session-end.sh — session-end hook for Claude Code
+#
+# Fires when the Claude Code session ends (including /exit). Reads the
+# transcript path from stdin JSON and runs `deja save-session --transcript`
+# to automatically extract and save memories from the session.
+#
+# Requires a provider configured: deja config set provider anthropic
+# (or openai, google, etc.). Exits silently if no provider is set.
+
+set -euo pipefail
+
+INPUT=$(cat)
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""')
+CWD=$(echo "$INPUT"        | jq -r '.cwd // ""')
+
+[ -z "$TRANSCRIPT" ] && exit 0
+[ ! -f "$TRANSCRIPT" ] && exit 0
+
+PROJECT=$(basename "$CWD")
+
+if [ -n "$PROJECT" ]; then
+    deja save-session --transcript "$TRANSCRIPT" --project "$PROJECT" 2>/dev/null || true
+else
+    deja save-session --transcript "$TRANSCRIPT" 2>/dev/null || true
+fi
+"""
+
+_DEJA_BLOCK_MARKER = "## Deja"
+
+_AGENT_CONFIGS: dict[str, dict] = {
+    "claude-code": {
+        "global": Path("~/.claude/CLAUDE.md"),
+        "project": Path("./CLAUDE.md"),
+    },
+    "gemini-cli": {
+        "global": Path("~/.gemini/GEMINI.md"),
+        "project": Path("./GEMINI.md"),
+    },
+    "codex": {
+        "global": Path("~/.codex/AGENTS.md"),
+        "project": Path("./AGENTS.md"),
+    },
+    "cursor": {
+        "global": Path("~/.cursor/rules/deja.md"),
+        "project": Path("./.cursorrules"),
+    },
+    "windsurf": {
+        "global": None,
+        "project": Path("./.windsurfrules"),
+    },
+}
+
+
+def _build_deja_block(project: Optional[str]) -> str:
+    project_flag = f" --project {project}" if project else ""
+    session_cmd = f"deja save-session --project {project}" if project else "deja save-session"
+    return (
+        f"## Deja\n"
+        f"\n"
+        f"At session START: run `deja load{project_flag} --context \"<brief description of what you're working on>\"`"
+        f" and read the output. Assemble the context string from the user's first message, CWD, and"
+        f" primary language before running the command.\n"
+        f"\n"
+        f"DURING the session, run `deja save` when you discover:\n"
+        f"- Something that took >10 min to figure out    → --type gotcha\n"
+        f"- A non-obvious architectural decision          → --type decision\n"
+        f"- A pattern reusable across files/projects      → --type pattern\n"
+        f"- A significant chunk of work completed         → --type progress\n"
+        f"- A user preference                             → --type preference\n"
+        f"\n"
+        f"At session END: run `{session_cmd}` to flush remaining context."
+    )
+
+
+def _inject_block(path: Path, block: str, force: bool) -> str:
+    """Inject or replace the deja block in a config file.
+
+    Returns "injected" | "replaced" | "already_configured".
+    """
+    if path.exists():
+        content = path.read_text(encoding="utf-8")
+        # Check for marker on its own line to avoid matching "## Deja Integration" etc.
+        has_marker = ("\n## Deja\n" in content or content.startswith("## Deja\n"))
+        if has_marker:
+            if not force:
+                return "already_configured"
+            # Replace: find ## Deja line, then scan to next ## heading or EOF.
+            lines = content.split("\n")
+            start = None
+            for i, line in enumerate(lines):
+                if line == _DEJA_BLOCK_MARKER:
+                    start = i
+                    break
+            if start is None:
+                # Marker present but not on its own line — fall through to append
+                pass
+            else:
+                end = len(lines)
+                for i in range(start + 1, len(lines)):
+                    if lines[i].startswith("## "):
+                        end = i
+                        break
+                # Strip trailing blank lines between block and next section
+                while end > start + 1 and lines[end - 1] == "":
+                    end -= 1
+                block_lines = block.split("\n")
+                new_lines = lines[:start] + block_lines + lines[end:]
+                path.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
+                return "replaced"
+        # Not found (or fallthrough) — append with leading blank line
+        sep = "\n" if content.endswith("\n") else "\n\n"
+        if content.endswith("\n\n"):
+            sep = ""
+        path.write_text(content + sep + block + "\n", encoding="utf-8")
+        return "injected"
+    else:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(block + "\n", encoding="utf-8")
+        return "injected"
+
+
+def _detect_claude_plugin() -> list[str]:
+    """Return a list of human-readable signals indicating the Claude Code plugin is active.
+
+    Checks four independent sources so partial installs are also caught:
+      1. ## Memory (deja) block in ~/.claude/CLAUDE.md (written by session-start.sh)
+      2. enabledPlugins entry containing "deja" in ~/.claude/settings.json
+      3. installed_plugins.json in ~/.claude/plugins/ containing a "deja" entry
+      4. CLAUDE_PLUGIN_ROOT hook commands in ~/.claude/settings.json (plugin-registered hooks)
+    """
+    signals: list[str] = []
+
+    # 1. CLAUDE.md block written by the plugin's session-start.sh
+    claude_md = Path("~/.claude/CLAUDE.md").expanduser()
+    if claude_md.exists():
+        try:
+            content = claude_md.read_text(encoding="utf-8")
+            if "\n## Memory (deja)\n" in content or content.startswith("## Memory (deja)\n"):
+                signals.append("## Memory (deja) block found in ~/.claude/CLAUDE.md")
+        except OSError:
+            pass
+
+    settings_path = Path("~/.claude/settings.json").expanduser()
+    settings_text = ""
+    settings: dict = {}
+    if settings_path.exists():
+        try:
+            settings_text = settings_path.read_text(encoding="utf-8")
+            settings = json.loads(settings_text)
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    # 2. enabledPlugins entry with "deja" in the key
+    for key, enabled in settings.get("enabledPlugins", {}).items():
+        if "deja" in key.lower() and enabled:
+            signals.append(f"plugin '{key}' enabled in ~/.claude/settings.json (enabledPlugins)")
+
+    # 3. installed_plugins.json registry
+    installed_plugins_path = Path("~/.claude/plugins/installed_plugins.json").expanduser()
+    if installed_plugins_path.exists():
+        try:
+            registry = json.loads(installed_plugins_path.read_text(encoding="utf-8"))
+            for key in registry.get("plugins", {}):
+                if "deja" in key.lower():
+                    signals.append(
+                        f"plugin '{key}' found in ~/.claude/plugins/installed_plugins.json"
+                    )
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    # 4. CLAUDE_PLUGIN_ROOT in settings.json hooks (plugin hooks registered by Claude Code)
+    if "CLAUDE_PLUGIN_ROOT" in settings_text:
+        signals.append(
+            "plugin hook commands (CLAUDE_PLUGIN_ROOT) found in ~/.claude/settings.json"
+        )
+
+    return signals
+
+
+def _detect_deja_setup(target_path: Path, agent: str) -> list[str]:
+    """Return signals indicating deja setup has already been run for this agent/path.
+
+    Checks the config file for the ## Deja block, and for claude-code additionally
+    checks for hook scripts and settings.json registrations.
+    """
+    signals: list[str] = []
+    display = str(target_path).replace(str(Path.home()), "~")
+
+    # 1. ## Deja block in the target config file
+    if target_path.exists():
+        try:
+            content = target_path.read_text(encoding="utf-8")
+            if "\n## Deja\n" in content or content.startswith("## Deja\n"):
+                signals.append(f"## Deja block found in {display}")
+        except OSError:
+            pass
+
+    if agent != "claude-code":
+        return signals
+
+    # 2-4. Hook scripts present in ~/.claude/hooks/
+    hooks_dir = Path("~/.claude/hooks").expanduser()
+    for name in ("deja-recall.sh", "deja-post-fail.sh", "deja-session-end.sh"):
+        if (hooks_dir / name).exists():
+            signals.append(f"{name} found in ~/.claude/hooks/")
+
+    # 5-7. Hook scripts registered in ~/.claude/settings.json
+    settings_path = Path("~/.claude/settings.json").expanduser()
+    if settings_path.exists():
+        try:
+            settings_text = settings_path.read_text(encoding="utf-8")
+            for name in ("deja-recall.sh", "deja-post-fail.sh", "deja-session-end.sh"):
+                if name in settings_text:
+                    signals.append(f"{name} registered in ~/.claude/settings.json")
+        except OSError:
+            pass
+
+    return signals
+
+
+def _install_claude_hooks() -> None:
+    """Write hook scripts and register them in ~/.claude/settings.json."""
+    hooks_dir = Path("~/.claude/hooks").expanduser()
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+
+    recall_path = hooks_dir / "deja-recall.sh"
+    post_fail_path = hooks_dir / "deja-post-fail.sh"
+    session_end_path = hooks_dir / "deja-session-end.sh"
+
+    for path, content in [
+        (recall_path, _RECALL_HOOK_SCRIPT.lstrip("\n")),
+        (post_fail_path, _POST_FAIL_HOOK_SCRIPT.lstrip("\n")),
+        (session_end_path, _SESSION_END_HOOK_SCRIPT.lstrip("\n")),
+    ]:
+        path.write_text(content, encoding="utf-8")
+        path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        display = str(path).replace(str(Path.home()), "~")
+        typer.echo(f"deja: hooks installed → {display}")
+
+    settings_path = Path("~/.claude/settings.json").expanduser()
+    settings_text = settings_path.read_text(encoding="utf-8") if settings_path.exists() else ""
+    try:
+        settings = json.loads(settings_text) if settings_text.strip() else {}
+    except json.JSONDecodeError:
+        settings = {}
+
+    hooks_obj = settings.setdefault("hooks", {})
+    changed = False
+
+    if "deja-recall.sh" not in settings_text:
+        hooks_obj.setdefault("PreToolUse", []).append({
+            "matcher": "Bash",
+            "hooks": [{"type": "command", "command": "~/.claude/hooks/deja-recall.sh"}],
+        })
+        changed = True
+
+    if "deja-post-fail.sh" not in settings_text:
+        hooks_obj.setdefault("PostToolUse", []).append({
+            "matcher": "Bash",
+            "hooks": [{"type": "command", "command": "~/.claude/hooks/deja-post-fail.sh"}],
+        })
+        changed = True
+
+    if "deja-session-end.sh" not in settings_text:
+        hooks_obj.setdefault("SessionEnd", []).append({
+            "hooks": [{"type": "command", "command": "~/.claude/hooks/deja-session-end.sh"}],
+        })
+        changed = True
+
+    if changed:
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        settings_path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+        typer.echo("deja: settings.json updated → hooks registered")
+
+
+@app.command()
+def setup(
+    agent: str = typer.Argument(..., help="Agent: claude-code, gemini-cli, codex, cursor, windsurf"),
+    project: Optional[str] = typer.Option(None, "--project", help="Write to local project config instead of global"),
+    hooks: bool = typer.Option(True, "--hooks/--no-hooks", help="Install hooks for claude-code (use --no-hooks to skip)"),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing deja block"),
+):
+    """Inject the deja memory protocol into an agent's config file.
+
+    Without --project, writes to the agent's global config (~/.claude/CLAUDE.md etc.).
+    With --project <name>, writes to the local project config (./CLAUDE.md etc.) and
+    scopes deja load/save-session to that project name.
+    """
+    if agent not in _AGENT_CONFIGS:
+        valid = ", ".join(sorted(_AGENT_CONFIGS.keys()))
+        typer.echo(f"deja: unknown agent '{agent}'. Valid: {valid}", err=True)
+        raise typer.Exit(1)
+
+    if agent == "claude-code":
+        signals = _detect_claude_plugin()
+        if signals:
+            lines = ["deja: Claude Code plugin installation detected — stopping."]
+            lines.append("The plugin and `deja setup` are separate paths; use one, not both.")
+            lines.append("Signals found:")
+            for s in signals:
+                lines.append(f"  • {s}")
+            lines.append(
+                "To switch to the manual path: uninstall the plugin, remove the "
+                "## Memory (deja) block from ~/.claude/CLAUDE.md, then re-run."
+            )
+            typer.echo("\n".join(lines), err=True)
+            raise typer.Exit(1)
+
+    cfg = _AGENT_CONFIGS[agent]
+
+    if project:
+        raw_path: Optional[Path] = cfg["project"]
+    else:
+        raw_path = cfg.get("global")
+        if raw_path is None:
+            typer.echo(
+                f"deja: {agent} has no known global config path. "
+                f"Use --project <name> to write to a local project config.",
+                err=True,
+            )
+            raise typer.Exit(1)
+
+    target_path = raw_path.expanduser()
+    display = str(target_path).replace(str(Path.home()), "~")
+
+    # Always run hook installation for claude-code — it's idempotent and new
+    # hook scripts may have been added since the initial setup.
+    if agent == "claude-code" and hooks:
+        _install_claude_hooks()
+
+    setup_signals = _detect_deja_setup(target_path, agent)
+    if setup_signals and not force:
+        lines = [f"deja: {agent} already configured — stopping."]
+        lines.append("Signals found:")
+        for s in setup_signals:
+            lines.append(f"  • {s}")
+        lines.append("Use --force to update.")
+        typer.echo("\n".join(lines))
+        raise typer.Exit(0)
+
+    block = _build_deja_block(project)
+    result = _inject_block(target_path, block, force)
+
+    if result == "replaced":
+        typer.echo(f"deja: {agent} configured (updated) → {display}")
+    else:
+        typer.echo(f"deja: {agent} configured → {display}")