prism-mem 0.1.0__tar.gz

prism_mem-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,200 @@
+# Prism — CLAUDE.md
+
+## What This Project Is
+
+Prism is a post-session knowledge crystallizer for AI coding agents. It reads Claude Code session transcripts (JSONL files) and git history, extracts structured semantic knowledge as triples, links them into a graph, and auto-regenerates the context files that every agent reads at session start (CLAUDE.md, .cursorrules, AGENTS.md).
+
+**The one-liner:** Every coding session leaves behind artifacts. Prism reads them and turns them into structured, linked, reusable knowledge — automatically, with no manual input from the user.
+
+**Package name:** `prism-mem` on PyPI. The CLI command is `prism`.
+
+---
+
+## Architecture
+
+### Data Flow
+
+```
+[User ends a coding session / makes a git commit]
+        ↓
+[git post-commit hook calls: prism crystallize --project .]
+        ↓
+[1] INGEST
+    - Read ~/.claude/projects/<encoded-path>/<session-uuid>.jsonl
+    - Read: git diff HEAD~1 HEAD  +  git log --oneline -20
+        ↓
+[2] EXTRACT
+    - Feed text chunks to kg-gen
+    - kg-gen returns NetworkX graph of (subject, predicate, object) triples
+        ↓
+[3] STORE + LINK
+    - Embed each triple via Anthropic embeddings API
+    - Store in SQLite (sqlite-vec) at ~/.prism/projects/<hash>/graph.db
+    - For each new triple: query sqlite-vec for nearest existing triples
+    - Create edges where similarity > threshold
+    - Detect staleness: same subject+predicate, different object → flag old triple
+        ↓
+[4] GENERATE
+    - Score all triples (recency + confidence + retrieval frequency)
+    - Take top-N triples → Claude Haiku → write CLAUDE.md
+    - Write same knowledge to .cursorrules and AGENTS.md formats
+        ↓
+[graph.db updated] + [constitution files written to project root]
+```
+
+### Storage Layout
+
+```
+~/.prism/
+└── projects/
+    └── <project-hash>/
+        └── graph.db         ← SQLite + sqlite-vec, one per project
+```
+
+Two tables:
+- `triples`: id, subject, predicate, object, confidence, embedding (blob), session_id, timestamp, stale (bool)
+- `edges`: from_id, to_id, edge_type, weight
+
+### MCP Server — 3 tools only, no more
+
+| Tool | What it does |
+|---|---|
+| `get_context()` | Returns current CLAUDE.md content — injected at session start |
+| `query_knowledge(question)` | Semantic search over the triple graph |
+| `crystallize(session_id)` | Manually trigger extraction for a session |
+
+---
+
+## Project Structure
+
+```
+prism-mem/
+├── CLAUDE.md                  ← You are here
+├── plan.md                    ← Build phases and completion criteria
+├── pyproject.toml             ← Package config, deps, entry point
+├── requirements.txt           ← Dev dependencies (for venv)
+├── prism_mem/
+│   ├── __init__.py
+│   ├── cli.py                 ← Click CLI: prism serve / ui / crystallize / hook / config
+│   ├── ingestion/
+│   │   ├── __init__.py
+│   │   ├── session_reader.py  ← Read ~/.claude/projects/ JSONL files
+│   │   └── git_reader.py      ← Read git diff + log via subprocess
+│   ├── extraction/
+│   │   ├── __init__.py
+│   │   └── extractor.py       ← kg-gen integration, chunking, triple output
+│   ├── storage/
+│   │   ├── __init__.py
+│   │   ├── db.py              ← SQLite setup, schema, migrations
+│   │   └── models.py          ← Triple and Edge dataclasses
+│   ├── linking/
+│   │   ├── __init__.py
+│   │   └── linker.py          ← Embed triples, find similar, create edges, staleness
+│   ├── constitution/
+│   │   ├── __init__.py
+│   │   └── generator.py       ← Score triples → Haiku → write CLAUDE.md etc.
+│   ├── server/
+│   │   ├── __init__.py
+│   │   ├── mcp_server.py      ← FastMCP server with 3 tools
+│   │   └── ui_server.py       ← FastAPI + Pyvis UI at localhost:7823
+│   └── config.py              ← Paths, constants, TOML config (load_config, get_model_string, get_api_key, is_config_complete, validate_provider)
+└── tests/
+    └── ...
+```
+
+---
+
+## Tech Stack — Do Not Deviate
+
+| Layer | Tool | Reason |
+|---|---|---|
+| Triple extraction | `kg-gen` | Already built, LLM + clustering, do not re-implement |
+| Vector storage | `sqlite-vec` | Local-first, no cloud, no ChromaDB |
+| In-memory graph | `networkx` | Interops directly with kg-gen output |
+| Graph visualization | `pyvis` | Generates self-contained D3 HTML from NetworkX, no JS needed |
+| MCP server | `fastmcp` | uvx-friendly, decorator-based |
+| Web UI | `fastapi` + `uvicorn` | Serves pyvis HTML + constitution at localhost:7823 |
+| CLI | `click` | Standard, clean |
+| LLM calls | `litellm` | Multi-provider abstraction — Anthropic, OpenAI, Gemini, Ollama, etc. |
+| Config | `~/.prism/config.toml` + built-in `tomllib` | Flat TOML, no external TOML dep, provider validated at set-time |
+
+No Memorix dependency. No LangChain. No ChromaDB. No cloud services. Everything runs locally.
+
+---
+
+## Key Decisions — Do Not Second-Guess These
+
+**Local-first.** All data lives in `~/.prism/`. No network calls except to the Anthropic API. Users own their data.
+
+**sqlite-vec, not ChromaDB.** One file, no server, no Docker. sqlite-vec is a SQLite extension that adds vector similarity search. It is sufficient for this use case.
+
+**kg-gen for extraction.** Do not write a custom triple extractor. kg-gen handles chunking, LLM calls, and entity clustering. Trust it.
+
+**3 MCP tools only.** `get_context`, `query_knowledge`, `crystallize`. Do not add tools. Scope is the whole point.
+
+**LiteLLM for all LLM calls.** Multi-provider via a single abstraction layer. Config stored in `~/.prism/config.toml` (provider + model + api_key). Default is Anthropic Haiku — fast and cheap. Provider validated at `prism config set` time using `litellm.provider_list`. extractor.py passes `provider/model` string to kg-gen (already dspy.LM / LiteLLM-compatible). generator.py uses `litellm.completion()` directly with OpenAI-compatible response format.
+
+**No Memorix dependency.** Prism is completely independent. Different database, different MCP server, different storage path. They are complementary but not coupled.
+
+**Constitution generates 3 files.** CLAUDE.md, .cursorrules, and AGENTS.md from the same triple set, formatted differently for each agent.
+
+---
+
+## Build Order
+
+Follow this order. Do not skip ahead. Each phase must produce testable output before moving to the next.
+
+1. **Project setup** — pyproject.toml, prism_mem/ package skeleton, move session_reader.py in
+2. **Session reader** — decode project path, find JSONL, parse events, return clean text chunks
+3. **Git reader** — subprocess calls to git, return diff + recent log as text
+4. **Extraction (kg-gen)** — chunk text, call kg-gen, inspect triple quality, iterate on chunking
+5. **Storage** — SQLite schema, sqlite-vec setup, store triples + embeddings
+6. **Linking** — embed triples, find similar via sqlite-vec, create edges, stale detection
+7. **Constitution generator** — score triples, call Haiku, write CLAUDE.md / .cursorrules / AGENTS.md
+8. **CLI** — `prism crystallize` wires phases 2–7 end to end
+9. **Git hook** — `prism hook install` writes the post-commit hook
+10. **MCP server** — FastMCP with 3 tools
+11. **Graph UI** — FastAPI + Pyvis, 3 routes: /graph, /memory, /constitution
+
+Phase 4 is the critical validation gate. If kg-gen produces poor-quality triples from real Claude Code sessions, the entire write path needs to change. Do not build phases 5–11 before validating phase 4 output on real data.
+
+---
+
+## What Prism Is Not
+
+- Not a memory store (Memorix does that)
+- Not a retrieval system (agentmemory does that)
+- Not a multi-agent orchestrator
+- Not a team coordination tool
+- Not a chat interface
+- Not a cloud service
+
+If a feature request does not directly serve "read session → extract triples → regenerate constitution," it does not belong in the v1 scope.
+
+---
+
+## Environment
+
+- Python 3.13
+- Virtual env at `.venv/`
+- LLM provider configured via `prism config set provider/model/api-key` (stored in `~/.prism/config.toml`)
+
+## Current State
+
+**Phases complete: 1–11 + post-shipping enhancements. All phases done. Next: Shipping.**
+
+### Done (summary)
+- **Phase 1**: Package skeleton, `pyproject.toml`, CLI stubs, `config.py`, `models.py`
+- **Phase 2**: `session_reader.py` — parses JSONL transcripts + subagents, chunk schema: `{role, content_type, content, timestamp, session_id, source}`
+- **Phase 3**: `git_reader.py` — `read_git_diff`, `read_git_log`, graceful on all edge cases
+- **Phase 4**: `extractor.py` — kg-gen + Haiku via LiteLLM, `extract_triples(text, context) -> list[tuple]`, `cluster=True`. Validated: 161 triples, good quality.
+- **Phase 5**: `db.py` — SQLite + sqlite-vec, `open_db`, `store_triple`, `get_all_triples`, `get_triple_by_id`, `mark_stale`. Embeddings via `sentence-transformers/all-MiniLM-L6-v2` (384-dim, local/free). DB at `~/.prism/projects/<hash>/graph.db`.
+- **Phase 6**: `linker.py` — `ingest_triple` (store → link → stale), `find_similar` (KNN via sqlite-vec, cosine sim from L2), `create_edge`, `check_and_mark_stale`. Order: link first while old triples are still non-stale, then mark stale.
+- **Phase 7**: `generator.py` — `write_constitution(project_path)`, `select_top_triples` (score = recency + confidence, top 30), `generate_claude_md/cursorrules/agents_md` via Haiku. Verified on real triples.
+- **Phase 8**: `cli.py` — `prism crystallize` wires all phases end-to-end. Progress output at each step, graceful errors, `--session` flag. Verified: 385 triples, 3 files written. Note: pipeline takes ~10min (kg-gen API calls are the bottleneck).
+- **Phase 9**: `cli.py` hook group — `prism hook install` writes `.git/hooks/post-commit` (shebang + prism block), appends if hook exists, idempotent. `prism hook uninstall` strips prism block, removes file if empty. Verified all three cases.
+- **Phase 10**: `mcp_server.py` — FastMCP server with 3 tools: `get_context` (reads CLAUDE.md), `query_knowledge` (embeds question → sqlite-vec KNN → returns top-5 triples with cosine similarity), `crystallize` (spawns `prism crystallize` in background, returns immediately). `prism serve --project .` wires it. Verified all 3 tools via `mcp.call_tool`.
+- **Phase 11**: `ui_server.py` — FastAPI + Pyvis at localhost:7823. Three routes: `/constitution` (CLAUDE.md in `<pre>` + Regenerate button via POST), `/memory` (searchable table of all 385 triples, active/stale badges, JS filter), `/graph` (Pyvis force-directed graph with nav injected, vis.js network). `prism ui --project . [--no-browser]` wires it. Verified: 200 on all routes, 385 total / 241 active shown, vis.js loaded in graph.
+- **Multi-provider config**: `config.py` refactored — removed `ANTHROPIC_API_KEY`/`HAIKU_MODEL` constants, replaced with `load_config()`, `get_model_string()`, `get_api_key()`, `is_config_complete()`, `validate_provider()` reading from `~/.prism/config.toml`. `generator.py` migrated from `anthropic.Anthropic` to `litellm.completion()`. `extractor.py` uses config accessors. `cli.py` adds `prism config set/show` commands with provider validation; `crystallize` checks `is_config_complete()` with clear setup instructions. `pyproject.toml`: removed `anthropic` direct dep, added `litellm>=1.0.0`.
+- **Code review fixes**: removed unused imports (`timezone` in generator.py), dead variables (`_CURATED_PROVIDERS` in config.py, `_VALID_KEYS` in cli.py); `ui_server.py` regenerate endpoint now surfaces errors instead of silently swallowing; `mcp_server.py` crystallize tool checks `is_config_complete()` before spawning subprocess.
+- **UI enhancements**: `/memory` table gains `Session` column (8-char truncation, full ID on hover via `title`). `/graph` node click shows a fixed sidebar listing all contributing session IDs with active/stale badges — data embedded as JSON at page-load, injected vis.js `click` listener accesses Pyvis's `var network` global. `/constitution` adds a `Copy` button beside Regenerate — reads `pre.innerText` via `navigator.clipboard.writeText`, shows `Copied!` for 1.5s.

prism_mem-0.1.0/.claude/context.md

@@ -0,0 +1,141 @@
+# Prism — Implementation Context
+
+Quick reference for coding agents. Read this before touching any file.
+
+---
+
+## What's built vs what's a stub
+
+| File | Status | Notes |
+|---|---|---|
+| `prism_mem/__init__.py` | stub | just `__version__` |
+| `prism_mem/config.py` | done | paths, model names, constants |
+| `prism_mem/cli.py` | **done** | `crystallize` fully wired; `serve`, `ui`, `hook` still stub |
+| `prism_mem/ingestion/session_reader.py` | **done** | fully implemented, tested on real data |
+| `prism_mem/ingestion/git_reader.py` | **done** | `read_git_diff`, `read_git_log` |
+| `prism_mem/extraction/extractor.py` | **done** | `extract_triples(text, context) -> list[tuple]` |
+| `prism_mem/storage/models.py` | **done** | `Triple` and `Edge` dataclasses |
+| `prism_mem/storage/db.py` | **done** | `open_db`, `store_triple`, `get_all_triples`, `get_triple_by_id`, `mark_stale` |
+| `prism_mem/linking/linker.py` | **done** | `ingest_triple`, `find_similar`, `create_edge`, `check_and_mark_stale`, `link_triple` |
+| `prism_mem/constitution/generator.py` | **done** | `write_constitution`, `select_top_triples`, `generate_claude_md/cursorrules/agents_md` |
+| `prism_mem/server/mcp_server.py` | stub | raises NotImplementedError |
+| `prism_mem/server/ui_server.py` | stub | raises NotImplementedError |
+
+---
+
+## session_reader.py — public API
+
+```python
+from prism_mem.ingestion.session_reader import (
+    read_latest_session,      # (project_path: str) -> list[dict]
+    read_session_by_id,       # (project_path: str, session_id: str) -> list[dict]
+    list_sessions,            # (project_path: str) -> list[Path]  newest first
+    parse_session,            # (jsonl_path: Path) -> list[dict]
+    parse_jsonl,              # (jsonl_path: Path, source: str) -> list[dict]
+    encode_project_path,      # (project_path: str) -> str
+    find_project_sessions,    # (project_path: str) -> Path
+)
+```
+
+**Chunk schema:**
+```python
+{
+    "role": "user" | "assistant",
+    "content_type": "text" | "thinking" | "summary",
+    "content": str,
+    "timestamp": str,        # ISO8601
+    "session_id": str,       # UUID from the JSONL line
+    "source": "main" | "<agent-id>",  # "main" = top-level session, agent-id = subagent
+}
+```
+
+**What's included / excluded:**
+- Included: user text, assistant text, assistant thinking blocks, summary events (compaction)
+- Excluded: tool_use, tool_result, file-history-snapshot, hook events, system injections
+- Subagent transcripts at `<uuid>/subagents/*.jsonl` are merged in, tagged with `source=<agent-id>`
+
+---
+
+## config.py — key constants
+
+```python
+from prism_mem.config import (
+    PRISM_HOME,               # ~/.prism
+    PROJECTS_DIR,             # ~/.prism/projects
+    CLAUDE_PROJECTS_DIR,      # ~/.claude/projects
+    ANTHROPIC_API_KEY,        # from env
+    SIMILARITY_THRESHOLD,     # 0.85
+    TOP_TRIPLES_FOR_CONSTITUTION,  # 30
+    HAIKU_MODEL,              # "claude-haiku-4-5-20251001"
+    UI_PORT,                  # 7823
+)
+```
+
+---
+
+## storage/models.py — dataclasses
+
+```python
+@dataclass
+class Triple:
+    subject: str
+    predicate: str
+    object: str
+    confidence: float = 1.0
+    embedding: bytes = b""
+    session_id: str = ""
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    stale: bool = False
+    id: int = 0
+
+@dataclass
+class Edge:
+    from_id: int
+    to_id: int
+    edge_type: str
+    weight: float
+```
+
+---
+
+## Environment
+
+- Python 3.13.5, venv at `.venv/`
+- **Always run with:** `DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib .venv/bin/python`
+  (macOS pyexpat linking workaround — required or imports fail)
+- `ANTHROPIC_API_KEY` must be set for any LLM calls
+- Package installed editable: `pip install -e .` already done
+
+---
+
+## Running session_reader manually
+
+```bash
+# from project root
+DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib .venv/bin/python prism_mem/ingestion/session_reader.py
+# or pass a project path:
+DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib .venv/bin/python prism_mem/ingestion/session_reader.py /path/to/project
+```
+
+---
+
+## git_reader.py — public API
+
+```python
+from prism_mem.ingestion.git_reader import read_git_diff, read_git_log
+
+read_git_diff(project_path: str) -> str   # git diff HEAD~1 HEAD, "" on any error/edge case
+read_git_log(project_path: str, n: int = 20) -> str  # git log --oneline -N
+```
+
+Both return `""` safely for: not a git repo, no commits, single commit (no HEAD~1).
+
+---
+
+## What's next (Phase 4 — critical gate)
+
+Implement `prism_mem/extraction/extractor.py` using kg-gen:
+- Chunk the combined text (session chunks + git diff + log)
+- Call kg-gen on each chunk with the Anthropic backend
+- Collect the NetworkX graph of `(subject, predicate, object)` triples
+- **Do not proceed to Phase 5 until triple quality is validated on real sessions**

prism_mem-0.1.0/.claude/plan.md

@@ -0,0 +1,271 @@
+# Prism — Build Plan
+
+Each phase has a clear completion test. Do not move to the next phase until the current one passes its test.
+
+---
+
+## Phase 1 — Project Setup ✅ DONE
+
+**Goal:** A proper Python package that can be installed and run as a CLI.
+
+**What to do:**
+- Create `pyproject.toml` with package metadata, dependencies, and the `prism` entry point
+- Create `prism_mem/` directory with `__init__.py`
+- Create all subdirectory stubs: `ingestion/`, `extraction/`, `storage/`, `linking/`, `constitution/`, `server/`
+- Move `ingestion/session_reader.py` into `prism_mem/ingestion/session_reader.py`
+- Create `prism_mem/config.py` for paths and constants
+- Create `prism_mem/cli.py` with stub Click commands: `crystallize`, `serve`, `ui`, `hook`
+
+**Done when:**
+- `pip install -e .` works with no errors
+- `prism --help` runs and shows the available commands
+- All stub commands run without crashing (they can just print "not implemented yet")
+
+---
+
+## Phase 2 — Session Reader ✅ DONE
+
+**Goal:** Given a project path, find and parse the most recent Claude Code session into clean text chunks.
+
+**What to do:**
+- Implement the project path encoder (slashes → hyphens)
+- Implement the session directory finder: look in `~/.claude/projects/<encoded-path>/`
+- List JSONL files sorted by modification time (newest first)
+- Parse JSONL: one JSON object per line
+- Extract text chunks from `type: "assistant"` events: pull `text` blocks and `thinking` blocks from `message.content`
+- Extract text chunks from `type: "user"` events: pull the user's question
+- Return a list of chunks with role, type, content, and timestamp
+
+**Done when:**
+- Point it at a real project that has Claude Code sessions
+- It prints the chunks cleanly: role, content preview, timestamp
+- The output is readable English, not raw JSON
+
+---
+
+## Phase 3 — Git Reader ✅ DONE
+
+**Goal:** Given a project path, return the last commit's diff and recent commit history as text.
+
+**What to do:**
+- Use `subprocess` to call `git diff HEAD~1 HEAD` in the project directory
+- Use `subprocess` to call `git log --oneline -20`
+- Handle the case where there are no commits or git is not initialized
+- Return both as plain text strings
+
+**Done when:**
+- Run it against any git repo
+- The diff output and log output print cleanly as text
+- No crashes on edge cases (new repo, no commits, not a git repo)
+
+---
+
+## Phase 4 — Extraction (Critical Validation Gate) ✅ DONE
+
+**Goal:** Feed real session text to kg-gen and evaluate the quality of the triples it returns.
+
+**What to do:**
+- Install kg-gen
+- Chunk the session text (kg-gen has a per-call input limit — find it and chunk accordingly)
+- Call kg-gen on each chunk with the appropriate LLM backend (Anthropic)
+- Collect the NetworkX graph output
+- Print every triple: subject, predicate, object
+
+**Done when:**
+- Run it on 2–3 real Claude Code sessions from different projects
+- The triples are specific and meaningful (e.g., `(auth module, uses, JWT)` not `(it, does, things)`)
+- Entities are being clustered correctly (same thing not appearing as 3 different node names)
+- You feel confident the triples would be useful 6 months from now
+
+**If the triples are low quality:**
+- Try different chunking strategies (smaller chunks, overlap, no overlap)
+- Try different kg-gen configuration options
+- Try filtering the input text (assistant-only, skip tool_use, include thinking)
+- Do not move to Phase 5 until you are satisfied with triple quality on real data
+
+---
+
+## Phase 5 — Storage ✅ DONE
+
+**Goal:** Persist triples and their embeddings in a local SQLite database with vector search.
+
+**What to do:**
+- Install sqlite-vec
+- Define the `Triple` dataclass: id, subject, predicate, object, confidence, embedding, session_id, timestamp, stale
+- Define the `Edge` dataclass: from_id, to_id, edge_type, weight
+- Create `~/.prism/projects/<project-hash>/graph.db` on first use
+- Implement `store_triple()`: embed the triple text, store row + embedding in sqlite-vec
+- Implement `get_all_triples()` and `get_triple_by_id()`
+
+**Done when:**
+- Run Phase 4 and pipe the output into storage
+- Query the DB with sqlite3 CLI and verify rows are there
+- Verify embeddings are stored (not null, not empty)
+
+---
+
+## Phase 6 — Linking ✅ DONE
+
+**Goal:** When a new triple is stored, find related existing triples and connect them. Detect stale facts.
+
+**What to do:**
+- Implement `find_similar(triple, top_k=5)`: query sqlite-vec for nearest neighbors by embedding
+- Implement `create_edge(from_id, to_id, edge_type, weight)`: write to edges table
+- Link triples where similarity > 0.85
+- Implement staleness: before storing a new triple, check if any existing triple has the same subject and predicate but a different object — if so, set `stale = True` on the old one
+
+**Done when:**
+- Store 20+ triples from a real session
+- Print all edges and verify they represent meaningful connections (JWT links to auth module, etc.)
+- Manually introduce a conflicting triple and verify the old one is flagged stale
+
+---
+
+## Phase 7 — Constitution Generator ✅ DONE
+
+**Goal:** Read the knowledge graph and produce a CLAUDE.md that accurately describes the project.
+
+**What to do:**
+- Score every non-stale triple: `score = recency_weight + confidence + retrieval_count`
+- Take the top 30 triples by score
+- Format them as a structured prompt for Claude Haiku
+- Call Haiku with the prompt and receive a CLAUDE.md
+- Write the output to `<project-root>/CLAUDE.md`
+- Also write `.cursorrules` (same content, simpler format for Cursor)
+- Also write `AGENTS.md` (same content, Codex format)
+
+**Done when:**
+- Run it against a project you've been working in with Claude Code
+- Open the generated CLAUDE.md
+- The content is accurate: it correctly identifies your tech stack, conventions, and key decisions
+- You would actually find it useful if you started a new session with it loaded
+
+This is the payoff moment. If the generated constitution is good, everything is working.
+
+---
+
+## Phase 8 — CLI (End-to-End Wire-Up) ✅ DONE
+
+**Goal:** `prism crystallize` runs the full pipeline from ingestion to constitution in one command.
+
+**What to do:**
+- Wire `prism crystallize --project <path>` to: read session → read git → extract → store → link → generate
+- Add a `--session <id>` flag to target a specific session instead of the most recent one
+- Print progress to stdout: "Reading session...", "Extracting triples...", "Generated CLAUDE.md"
+- Handle errors gracefully: missing sessions, no git repo, API errors
+
+**Done when:**
+- Run `prism crystallize` in any project that has Claude Code sessions
+- CLAUDE.md, .cursorrules, and AGENTS.md appear (or are updated) in the project root
+- The whole pipeline takes under 60 seconds
+
+---
+
+## Phase 9 — Git Hook ✅ DONE
+
+**Goal:** Prism runs automatically after every commit without the user thinking about it.
+
+**What to do:**
+- Implement `prism hook install`: write `.git/hooks/post-commit` in the current project
+- The hook calls `prism crystallize --project $(git rev-parse --show-toplevel)` in the background (`&`)
+- Implement `prism hook uninstall`: remove the hook
+
+**Done when:**
+- Install the hook in a test repo
+- Make a commit
+- Within 60 seconds, CLAUDE.md is updated without you doing anything
+
+---
+
+## Phase 10 — MCP Server ✅ DONE
+
+**Goal:** Any agent that supports MCP can call Prism's 3 tools.
+
+**What to do:**
+- Implement FastMCP server in `server/mcp_server.py`
+- Tool 1: `get_context()` — returns the current CLAUDE.md content for the project
+- Tool 2: `query_knowledge(question: str)` — embeds the question, queries sqlite-vec, returns top-5 matching triples as structured text
+- Tool 3: `crystallize(session_id: str = None)` — triggers the full pipeline, returns confirmation
+- Wire `prism serve` CLI command to start the FastMCP server in stdio mode
+
+**Done when:**
+- Add Prism to Claude Code: `claude mcp add prism -- prism serve`
+- Start a new Claude Code session in a project
+- Call `get_context()` via Claude Code and verify it returns the correct CLAUDE.md
+- Call `query_knowledge("how does auth work")` and verify it returns relevant triples
+
+---
+
+## Phase 11 — Graph UI ✅ DONE
+
+**Goal:** `prism ui` opens a local browser UI where the user can explore the knowledge graph.
+
+**What to do:**
+- Implement FastAPI app in `server/ui_server.py`
+- Route `/graph`: load graph.db into NetworkX, render with Pyvis, serve the HTML
+- Route `/memory`: serve a searchable table of all triples (HTML, no JS framework needed)
+- Route `/constitution`: serve current CLAUDE.md content with a "Regenerate" button that calls the constitution generator
+- Wire `prism ui` CLI command to start uvicorn and open `http://localhost:7823` in the browser
+
+**Done when:**
+- Run `prism ui`
+- Browser opens at localhost:7823
+- The force-directed graph is visible and interactive (draggable nodes, hoverable edges)
+- The constitution tab shows the current CLAUDE.md with a working Regenerate button
+
+**Enhancements added post-completion (see Post-Shipping section):**
+- `/memory`: Session column with hover for full ID
+- `/graph`: Node-click sidebar showing contributing sessions with active/stale status
+- `/constitution`: Copy button with clipboard feedback
+
+---
+
+## Shipping
+
+**When all 11 phases pass their tests:**
+- Finalize `pyproject.toml` (version 0.1.0, correct classifiers, description)
+- Write `README.md`: one-liner, 3-command quickstart, architecture diagram, link to PyPI
+- `uv build` + `uv publish` to PyPI
+- Test `uvx prism-mem serve` from a fresh environment (no install needed)
+- Add to Claude Code: `claude mcp add prism -- uvx prism-mem serve`
+
+---
+
+## Post-Shipping Enhancements
+
+Work completed after all 11 phases. None of these change the DB schema or add new routes.
+
+### Multi-provider LLM config ✅ DONE
+- `~/.prism/config.toml` stores `provider`, `model`, `api_key` (flat TOML, built-in `tomllib`)
+- `config.py` exports `load_config`, `save_config`, `get_model_string` (`provider/model`), `get_api_key`, `is_config_complete`, `validate_provider` (uses `litellm.provider_list`)
+- `generator.py` switched from `anthropic.Anthropic` client to `litellm.completion()`; response via `response.choices[0].message.content`
+- `extractor.py` uses `get_model_string()` / `get_api_key()` — kg-gen/dspy.LM already speaks LiteLLM format
+- `cli.py` adds `prism config set {provider|model|api-key}` (provider validated at set-time) and `prism config show` (api-key masked)
+- `crystallize` now checks `is_config_complete()` with actionable error instead of crashing on missing env var
+- `pyproject.toml`: removed `anthropic` direct dep, added `litellm>=1.0.0`
+
+### Code review fixes ✅ DONE
+- Removed unused `timezone` import in `generator.py`
+- Removed dead `_CURATED_PROVIDERS` in `config.py`, `_VALID_KEYS` in `cli.py`
+- `ui_server.py` `/constitution/regenerate` now returns error page instead of silently swallowing exceptions
+- `mcp_server.py` `crystallize` tool checks `is_config_complete()` before spawning subprocess
+
+### UI enhancements ✅ DONE
+- `/memory`: added `Session` column after `Timestamp` — 8-char truncation with full ID in `title` attribute
+- `/graph`: node click opens a fixed sidebar listing contributing session IDs with active/stale badges. Node info built server-side from all triples (including stale), embedded as JSON, accessed via injected vis.js `network.on('click', ...)` listener. `</` escaped to `<\/` in embedded JSON.
+- `/constitution`: added `Copy` button beside Regenerate. Reads `pre.innerText` via `navigator.clipboard.writeText`, label swaps to `Copied!` for 1.5s then restores.
+
+---
+
+## Scope Rules
+
+If it is not in the 11 phases above, it is not in v1. Specifically:
+
+- No multi-agent orchestration
+- No team features
+- No cloud sync or remote storage
+- No chat interface
+- No Memorix integration (that is v2 if ever)
+- No support for agents other than Claude Code for ingestion (Cursor/Codex use the MCP read path, not ingestion)
+
+The v1 goal is: one user, one machine, any agent that speaks MCP, automatic context regeneration after every commit.

prism_mem-0.1.0/.claude/settings.local.json

@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 -m ensurepip --version)",
+      "Bash(python3 -c \"import ensurepip; print\\(ensurepip.__file__\\)\")",
+      "Bash(brew list *)",
+      "Bash(pyenv versions *)",
+      "Read(//usr/local/lib/**)",
+      "Read(//opt/homebrew/lib/python3.14/**)",
+      "Bash(/opt/homebrew/bin/python3.14 *)",
+      "Bash(otool *)",
+      "Read(//opt/homebrew/Cellar/expat/2.8.1/lib/**)",
+      "Bash(nm /opt/homebrew/opt/expat/lib/libexpat.dylib)",
+      "Bash(/Users/rahul/Desktop/Projects/prism-mem/.venv/bin/python *)",
+      "mcp__plugin_claude-mem_mcp-search__get_observations",
+      "Bash(curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py)",
+      "Bash(DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib /Users/rahul/Desktop/Projects/prism-mem/.venv/bin/python /tmp/get-pip.py)",
+      "Bash(DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib .venv/bin/pip install *)",
+      "Bash(sort -k6 -r)",
+      "Bash(DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib .venv/bin/python *)",
+      "Bash(grep -v \"^$\\\\|LiteLLM\\\\|WARNING\\\\|INFO\")",
+      "Bash(grep -v \"^$\")",
+      "Bash(sqlite3 *)",
+      "Skill(claude-mem:make-plan)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" http://127.0.0.1:7823/graph)",
+      "Bash(curl -s http://127.0.0.1:7823/graph)",
+      "Bash(curl -s http://127.0.0.1:7823/memory)",
+      "Bash(kill %1)"
+    ]
+  }
+}