@gi4nks/ph 1.4.0 → 1.6.0

package/docs/ph-manual.md

@@ -1,358 +1,479 @@
-# ph — Prompt History CLI
+# ph — Prompt History and Project Memory
 
-**Architecture, Hook System & Usage Guide**
+**Zero-friction capture, semantic search, project memory, and MCP-based knowledge retrieval for AI CLI tools.**
 
 ---
 
 ## 1. Overview
 
-ph is a transparent capture layer for AI CLI tools such as Claude Code and Gemini CLI. Every prompt you type — and the AI response that follows — is automatically saved to a local SQLite database with full-text and semantic search, Git context, and optional background analysis.
+ph is a transparent observability and knowledge layer for AI CLI tools (Claude Code, Codex CLI, Gemini CLI, OpenCode, etc.). It automatically records every prompt+response into a local SQLite database with full-text search, semantic vector search, LLM-based analysis, Git context snapshots, session grouping, and an interactive TUI browser.
 
-The core design principle is zero friction: ph never interrupts your workflow. Capture happens silently in the background. Your AI sessions remain unchanged.
+**Core principle:** ph captures conversations without changing the normal tool workflow. Optional analysis turns captured history into project summaries and memories that can be searched locally or requested by an MCP client. Capture and full-text search work without an LLM provider; analysis, embeddings, and semantic search require the configured provider.
 
 ### Key Features
 
-- **Automatic Capture** — saves prompts, responses, and metadata without any manual action
-- **Git Context** — records current branch, modified files, and diff at capture time
-- **Full-text & Semantic Search** — FTS5 text search and vector-based semantic search (via Ollama embeddings)
-- **Background Analysis** — automatic role/tag/relevance classification via Ollama or Gemini
-- **Interactive TUI** — browse, filter, edit, re-run, and export your history with `ph browse`
-- **Privacy First** — all data stays local; no data ever leaves your machine
+- **Automatic capture** via hooks (Claude Code, Codex CLI, Gemini CLI, OpenCode plugin) or wrapper mode
+- **Full-text search** (FTS5) and **semantic vector search** (Ollama embeddings, 768-dim via sqlite-vec)
+- **LLM analysis** — role/tag/relevance classification, summary extraction, key insights, technical decisions
+- **Project memory** — per-project accumulated knowledge with deduped insights and decisions
+- **MCP server** — tools for agents to search memories, check project knowledge, get context
+- **Interactive TUI** — browse, filter, edit, star, re-run, export prompts
+- **Session grouping** — automatic conversation grouping with cohesion scoring
+- **Git context** — records branch, modified files, and diff at capture time
+- **Background analysis** — async LLM processing after each capture (optional)
+- **Retention & archiving** — configurable auto-archive of old/low-relevance prompts
+- **Remote sync** — push/pull prompt history across machines via HTTP server
+- **Local-first storage** — the database stays on the configured machine unless optional remote sync is enabled; no telemetry is sent
 
 ---
 
-## 2. Architecture
+## 2. Installation
 
-ph uses a two-tier storage model: a SQLite database with FTS5 full-text indexing for fast retrieval, and a JSON config file for runtime settings. Both live in your home directory by default.
+```bash
+# Via npm
+npm install -g @gi4nks/ph
 
-### Storage Layout
+# From source
+git clone git@github.com:gi4nks/ph.git
+cd ph
+npm install
+npm run build
+npm link
+```
 
-| Item | Default Path | Description |
-|------|-------------|-------------|
-| Database | `~/.prompt_history.db` | SQLite with FTS5 + vector embeddings |
-| Config | `~/.ph_config.json` | JSON config file (0o600 permissions) |
+### Quick config
 
-The database uses WAL (Write-Ahead Logging) mode, enabling concurrent reads and writes. This is essential for the background analysis system, which processes prompts asynchronously without blocking your terminal session.
+```bash
+ph config set background-analysis true   # auto-analyze after each capture
+ph config set analyze-provider ollama     # ollama (default) or gemini
+ph config set ollama-model llama3.1:latest
+```
 
 ---
 
-## 3. The Hook System
+## 3. Capture Modes
 
-The hook system is ph's most powerful integration mechanism. Rather than requiring you to manually invoke ph for each session, hooks let the AI CLI tools themselves notify ph after every interaction — automatically, silently, and without any impact on response latency.
+### 3a. Hook mode (recommended)
 
-> **Key insight:** Hooks are post-action handlers registered inside the AI tool's own config. ph never wraps or intercepts the AI process. The AI runs normally; the hook fires after the session ends.
+AI CLI tools invoke `ph log` automatically after each interaction.
 
-### How Hooks Work
+**Claude Code** — `hooks/claude/ph-hook.sh`:
+```bash
+ln -sf $(pwd)/hooks/claude/ph-hook.sh ~/.claude/ph-hook.sh
+# Add to ~/.claude/settings.json:
+# "hooks": { "Stop": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "~/.claude/ph-hook.sh", "async": true }] }] }
+```
 
-Each supported AI CLI tool exposes a native hook mechanism:
+**Gemini CLI** — `hooks/gemini/ph-hook.sh`:
+```bash
+ln -sf $(pwd)/hooks/gemini/ph-hook.sh ~/.gemini/ph-hook.sh
+# Add to ~/.gemini/settings.json:
+# "hooks": { "AfterAgent": [{ "hooks": [{ "type": "command", "command": "~/.gemini/ph-hook.sh" }] }] }
+```
 
-- **Claude Code** — provides a `Stop` hook, triggered after each agent session completes
-- **Gemini CLI** — provides an `AfterAgent` hook, triggered after each agent turn
+**OpenCode** — plugin at `hooks/opencode/ph-plugin.ts`:
+```bash
+./hooks/opencode/install.sh   # global install
+```
 
-When the hook fires, the AI tool passes a JSON payload on stdin to your registered script. The script reads that payload, extracts the prompt and response, and pipes the data to `ph log` — which persists everything to the local SQLite database.
+**Codex CLI** — see [the Codex hook setup](../hooks/codex/README.md). The Stop
+hook imports the active rollout transcript. To import existing sessions, run
+`ph import codex --dry-run` and then `ph import codex`.
 
-The entire operation runs in the background using shell job control (`& + disown`), so it never adds latency to your terminal session and never blocks the AI tool from exiting.
+### 3b. Wrapper mode
 
----
+```bash
+ph claude "explain goroutines"
+ph codex exec "explain goroutines"
+ph gemini "refactor this code"
+ph --ph-role debug --ph-tag auth claude "fix JWT expiration"
+```
 
-### Claude Code Hook
+### 3c. Direct log
 
-#### How Claude Code delivers data
+```bash
+ph log --tool claude --prompt "your prompt" --response "response text"
+echo '{"tool":"claude","prompt":"hi","response":"hello"}' | ph log --stdin
+```
 
-When the `Stop` hook fires, Claude Code sends a JSON object on stdin:
+---
 
-```json
-{
-  "session_id": "abc123...",
-  "transcript_path": "/path/to/session.jsonl"
-}
+## 4. CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `ph` (no args) | Open interactive TUI browser |
+| `ph <tool> [args...]` | Wrapper mode — run tool + capture |
+| `ph search [query]` | Full-text search prompts |
+| `ph search --semantic <query>` | Semantic (vector) search |
+| `ph search --archive` | Search archived prompts |
+| `ph search -i <query>` | Open results in interactive TUI |
+| `ph last [n]` | Show last N prompts |
+| `ph context [query]` | Get RAG context for current project |
+| `ph sessions` | Group prompts into work sessions |
+| `ph timeline <project>` | Full chronological project history |
+| `ph stats` | History statistics |
+| `ph cluster -k 5` | K-means clustering on embeddings |
+| `ph analyze` | LLM analysis of untagged prompts |
+| `ph analyze-reusability` | Reusability scoring |
+| `ph cleanup` | Remove useless prompts (length/duplicates) |
+| `ph cleanup --retention` | Archive old/unqualified prompts per retention policy |
+| `ph cleanup-reusability` | Cleanup by reusability score |
+| `ph star <id>` | Toggle bookmark |
+| `ph export <id>` | Export prompt (txt/json/md) |
+| `ph import gemini|claude|opencode|codex` | Import from AI CLI history |
+| `ph log --tool <name> ...` | Direct log (hook target) |
+| `ph embed-all` | Generate embeddings for all prompts |
+| `ph config get|set <key> <value>` | View/edit config |
+| `ph vacuum` | Compact SQLite database |
+| `ph memory-migrate` | Merge existing memories into project_summaries |
+| `ph mcp` | Start MCP stdio server |
+| `ph server --port 3001` | Start HTTP REST server |
+| `ph remote push|pull|status` | Sync with remote ph server |
+| `ph chat <tool> <prompt>` | Run tool with project context injected |
+| `ph ollama-models` | List available Ollama models |
+
+### Search options
+
+```
+-i / --interactive    Open in TUI browser
+--tool <name>         Filter by tool
+--project <name>      Filter by project
+--language <lang>     Filter by language
+--role <role>         Filter by role
+--tag <tag>           Filter by tag
+--starred             Show only starred
+--semantic            Use semantic (vector) search
+--archive             Search archived prompts
+--since YYYY-MM-DD    Start date
+--until YYYY-MM-DD    End date
+--limit <n>           Max results (default 50)
+--top                 Quality >= 8
+--min-quality <n>     Min quality (0-10)
+--min-relevance <n>   Min relevance (0-10)
+--full                Show full prompt text
 ```
 
-The transcript is a JSONL file — one JSON object per line — containing the full session history. Each line is one of:
+### Context options
 
-| Turn type | Identifier |
-|-----------|-----------|
-| Human turn | Has `promptId` key; `message.content` is a plain string |
-| Tool result | Has `toolUseResult` key; `message.content` is an array |
-| Assistant turn | `message.role == "assistant"`; content is an array of typed blocks |
+```
+--project <name>      Project name (default: auto-detect)
+--limit <n>           Max results (default 5)
+--prompts-only        Skip project knowledge, show only prompts
+--memories-only       Skip prompts, show only project knowledge
+--verbose             Include full prompt text
+```
 
-#### What the hook script does
+### Sessions options
 
-1. Reads the hook input from stdin to obtain the transcript path
-2. Uses `jq` with slurp mode to parse the entire JSONL in one pass
-3. Filters for genuine human turns: must have `promptId`, string content, and no `toolUseResult` key
-4. Extracts the last human turn as the prompt
-5. Scans assistant turns for the last `text`-type block as the response
-6. Builds a JSON payload with `tool`, `prompt`, `response`, and `workdir` fields
-7. Pipes the payload to `ph log` running in the background (`& + disown`)
-8. Exits `0` unconditionally — Claude Code is never blocked
+```
+--gap-hours <n>       Hours gap to split sessions (default 2)
+--limit <n>           Max sessions (default 20)
+--min-size <n>        Min prompts per session (default 1)
+--no-cohesion         Skip semantic cohesion computation
+--export <n>          Export session N as markdown
+```
 
-#### Hook installation — Claude Code
+### Cluster options
 
-```bash
-# Step 1: link the hook script
-ln -sf /path/to/ph/hooks/claude/ph-hook.sh ~/.claude/ph-hook.sh
-
-# Step 2: register in ~/.claude/settings.json
-{
-  "hooks": {
-    "Stop": [
-      {
-        "matcher": ".*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "~/.claude/ph-hook.sh",
-            "async": true
-          }
-        ]
-      }
-    ]
-  }
-}
+```
+-k <number>           Number of clusters (default 5)
+--limit <n>           Max prompts per cluster to show (default 3)
 ```
 
 ---
 
-### Gemini CLI Hook
+## 5. TUI Keybindings
 
-#### How Gemini CLI delivers data
+| Key | Action |
+|-----|--------|
+| `Up` / `Down`, `Page Up` / `Page Down` | Navigate list |
+| `Tab` | Switch pane (wide mode) |
+| `1`, `2`, `3` | Switch prompt/response/memory tab |
+| `y` | Copy to clipboard |
+| `s` | Toggle star |
+| `e` | Edit metadata |
+| `r` | Rerun prompt (edit before launch) |
+| `Shift+C` | Chat mode: launch tool with project context |
+| `x` | Delete entry |
+| `/` | Search |
+| `o` | Settings panel (toggle auto-analysis, view config) |
+| `f` | Filter panel (flat list, Enter toggle, letter jump) |
+| `c` | Clear all filters |
+| `q` / `Escape` | Quit / back |
+
+### TUI components
+
+- **SearchBar** — always visible spotlight bar at top
+- **FilterPanel** — flat scrollable list of filter options with counts `[N]`, toggle with Enter, jump by letter
+- **SettingsView** — config viewer/editor (auto-analysis toggle, ollama URL/model, filters)
+- **PreviewPane** — three tabs (prompt/response/memory). Memory tab shows project-level knowledge
+- **ListEntry** — role marker, analysis status, star, Q/R badges, optional summary line
+- **Footer** — context-sensitive hints (shows `C:chat` only when entry has project)
 
-Gemini CLI's `AfterAgent` hook is simpler: it delivers the prompt and response directly in the stdin payload, with no transcript file to parse:
+---
+
+## 6. Project Memory System
+
+ph maintains two levels of per-project knowledge:
+
+### 6a. `project_summaries` (curated, 1 row per project)
+
+Accumulated knowledge with deduped insights and decisions. Updated on every analysis. Primary source for MCP tools.
 
-```json
-{
-  "session_id": "...",
-  "transcript_path": "...",
-  "cwd": "/path/to/workdir",
-  "hook_event_name": "AfterAgent",
-  "timestamp": "...",
-  "prompt": "the user's prompt text",
-  "prompt_response": "the assistant's full response text"
-}
+```bash
+# View accumulated project knowledge
+ph context --project myproject
+
+# Via MCP (for AI agents)
+# get_project_summary(project: "myproject")
 ```
 
-#### What the hook script does
+### 6b. `memories` (append-only timeline)
 
-1. Reads the JSON payload from stdin
-2. Extracts `prompt`, `prompt_response`, and `cwd` directly via `jq`
-3. Builds a JSON payload with `tool`, `prompt`, `response`, and `workdir` fields
-4. Pipes to `ph log` in the background
-5. Exits `0` unconditionally
+Full chronological history of every analysis run. Preserved for detailed audit.
 
-#### Hook installation — Gemini CLI
+### Memory migration
+
+If you have existing data from before the evolution phases:
 
 ```bash
-# Step 1: link the hook script
-ln -sf /path/to/ph/hooks/gemini/ph-hook.sh ~/.gemini/ph-hook.sh
-
-# Step 2: register in ~/.gemini/settings.json
-{
-  "hooks": {
-    "AfterAgent": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "~/.gemini/ph-hook.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
+ph memory-migrate   # one-time: merge all memories into project_summaries
 ```
 
 ---
 
-### OpenCode Hook
-
-OpenCode uses a JavaScript/TypeScript **plugin** system (rather than shell scripts). The `ph` integration is a plugin that hooks into OpenCode's message lifecycle to capture prompts and responses.
+## 7. Retention & Archiving
 
-#### How the plugin captures data
+Configurable auto-archiving to keep the database lean:
 
-The plugin registers two hooks inside OpenCode's runtime:
+```bash
+# Configure
+ph config set retentionDays 90            # archive prompts older than 90 days
+ph config set retentionMinRelevance 3     # prompts below this relevance archived first
+ph config set retentionMinStarred true    # starred prompts never archived
+ph config set retentionMinAnalyzed true   # analyzed prompts never archived
 
-| Hook | Purpose |
-|------|---------|
-| `chat.message` | Intercepts every message in the conversation. User messages become prompts; assistant messages become response snapshots. |
-| `experimental.text.complete` | Fires after streaming completes. Replaces the snapshot with the full, final response text. |
+# Run retention cleanup
+ph cleanup --retention                    # archive matching prompts
+ph cleanup --retention --dry-run          # preview only
 
-**Data flow:**
+# Search archived prompts
+ph search --archive
 
-```
-User types prompt
-  → chat.message fires (role: user)
-  → plugin stores the prompt text + metadata (agent, model, workdir)
-
-Assistant streams response
-  → experimental.text.complete fires for each text part
-  → plugin accumulates the complete response text
-
-Next user message or session end
-  → plugin pairs prompt + accumulated response
-  → pipes {"tool":"opencode","prompt":"...","response":"..."} to ph log
-  → runs in background — never blocks OpenCode
+# Auto-purge: entries older than 2x retentionDays are deleted during cleanup
 ```
 
-#### Hook installation — OpenCode
+---
 
-OpenCode loads plugins from two directories:
-- `~/.config/opencode/plugins/` — global (all projects)
-- `.opencode/plugins/` — per-project
+## 8. Background Analysis
 
-**Option A: Quick install (global)**
+When enabled, every `ph log` automatically spawns a detached child process that analyzes the new entry (role, tags, relevance, summary, key insights, technical decisions).
 
 ```bash
-# Link the plugin into OpenCode's global plugin directory
-mkdir -p ~/.config/opencode/plugins
-ln -sf /path/to/ph/hooks/opencode/ph-plugin.ts ~/.config/opencode/plugins/ph-plugin.ts
+ph config set background-analysis true
 ```
 
-Or use the install script:
+Analysis uses Ollama by default (requires `ollama serve` running). Configure:
 
 ```bash
-./hooks/opencode/install.sh              # global (default)
-./hooks/opencode/install.sh --project    # current project only
+ph config set analyze-provider gemini     # use Gemini instead
+ph config set gemini-api-key "YOUR_KEY"
+ph config set ollama-model llama3.1:latest
+ph config set ollama-embed-model nomic-embed-text-v2-moe
 ```
 
-**Option B: Manual copy**
+---
+
+## 9. MCP Server
+
+ph exposes an MCP (Model Context Protocol) server over stdio for AI agents:
 
 ```bash
-cp hooks/opencode/ph-plugin.ts ~/.config/opencode/plugins/
+ph mcp
 ```
 
-The plugin is automatically loaded on the next OpenCode startup. No config changes needed — Bun handles TypeScript natively.
+### Available tools
+
+| Tool | Description |
+|------|-------------|
+| `search_project_memory` | Semantic search + fallback to project_summaries |
+| `get_project_context` | Merged summary + recent memories + recent prompts |
+| `get_project_summary` | Accumulated key insights and technical decisions |
+| `check_project_knowledge` | Before implementing: checks memories + prompts for existing work |
+| `save_decision` | Persist an architectural decision to memory + summaries |
+| `search_prompts` | Full-text search over prompt history |
+| `get_prompt` | Full details by ID |
+| `search_prompts_semantic` | Vector search over prompts |
+| `get_project_timeline` | Full chronological project history |
+| `get_project_diff` | Compare project state between dates |
+| `list_prompts` | Paginated prompt listing |
 
-**Verify:**
-
-```bash
-# Start OpenCode — the plugin loads silently
-opencode
+---
 
-# Check that prompts are being captured
-ph search --tool opencode --limit 3
-```
+## 10. HTTP Server & Remote Sync
 
-**Uninstall:**
+Share prompt history across machines:
 
 ```bash
-rm ~/.config/opencode/plugins/ph-plugin.ts
+# Start server
+ph server --port 3001 --host 0.0.0.0
+
+# From another machine
+ph config set remote-url http://server-ip:3001
+ph remote push      # send local unsynced prompts
+ph remote pull      # fetch remote prompts
+ph remote status    # show sync state
 ```
 
+Every `ph log` auto-pushes to remote if configured (fire-and-forget, never blocks).
+
 ---
 
-### Hook Comparison
+## 11. Database
 
-| Aspect | Claude Code | Gemini CLI | OpenCode |
-|--------|------------|------------|----------|
-| Hook mechanism | `Stop` shell script | `AfterAgent` shell script | JS/TS plugin |
-| Data delivery | `transcript_path` (JSONL) | Direct JSON on stdin | Event hooks (`chat.message`, `experimental.text.complete`) |
-| Prompt extraction | Parse JSONL with `jq` slurp | `jq .prompt` | `message.role === 'user'` parts |
-| Response extraction | Last assistant text block | `jq .prompt_response` | `experimental.text.complete` accumulation |
-| Async support | Yes (`async: true`) | Yes (`& + disown`) | Yes (Promise fire-and-forget) |
-| Blocks AI exit? | Never | Never | Never |
-| Install method | Symlink + settings.json | Symlink + settings.json | Copy plugin file to `plugins/` dir |
+**Location:** `~/.prompt_history.db` (configurable via `ph config set db-path`)
 
----
+**Tables:**
 
-## 4. Installation
+| Table | Purpose |
+|-------|---------|
+| `prompts` | Main prompt+response storage with FTS5 index |
+| `prompts_archive` | Archived (retention-aged) prompts |
+| `memories` | Append-only per-project analysis timeline |
+| `project_summaries` | Single curated row per project with merged knowledge |
+| `vec_embeddings` | Vector embeddings (768-dim float, sqlite-vec) |
+| `embeddings` | Legacy BLOB embeddings (migrated on connect) |
 
-### From Source
+**Maintenance:**
 
 ```bash
-git clone git@github.com:gi4nks/ph.git
-cd ph
-npm install
-make build
-make install    # installs the global 'ph' symlink
+ph vacuum              # compact DB
+ph cleanup             # remove short/trivial/duplicate prompts
+ph cleanup --retention # archive per retention policy
+ph embed-all           # (re)generate all embeddings
 ```
 
-### Via npm
-
-```bash
-# Install globally:
-npm install -g @gi4nks/ph
-```
+---
 
-### Initial Configuration
+## 12. Filter Pipeline
 
-```bash
-# Set your Gemini API key (optional — Ollama works without it)
-ph config set gemini-api-key "YOUR_KEY"
+Before saving, ph filters out:
 
-# Choose your analysis provider
-ph config set analyze-provider ollama   # default, fully local
-# ph config set analyze-provider gemini  # cloud alternative
+- Prompts shorter than `filterMinLength` (default 15 chars)
+- Non-printable content
+- Trivial patterns (single chars, common noise)
+- Exact duplicates (within last 7 days)
+- Low-relevance prompts (when `--min-relevance` is set)
 
-# Enable background analysis
-ph config set background-analysis true
+Configure:
 
-# Optional: move the database to a custom location
-ph config set db-path "/path/to/your/custom.db"
+```bash
+ph config set filter-min-length 20
+ph config set filter-min-relevance 3
 ```
 
 ---
 
-## 5. Usage
+## 13. Configuration (`~/.ph_config.json`)
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `dbPath` | `~/.prompt_history.db` | SQLite database path |
+| `analyzeProvider` | `ollama` | LLM provider: `ollama` or `gemini` |
+| `ollamaUrl` | `http://localhost:11434` | Ollama server URL |
+| `ollamaModel` | `llama3.1:latest` | Analysis model |
+| `ollamaEmbedModel` | `nomic-embed-text-v2-moe` | Embedding model |
+| `geminiApiKey` | — | Gemini API key |
+| `backgroundAnalysis` | `false` | Auto-analyze after each capture |
+| `filterMinLength` | `15` | Min prompt length to keep |
+| `filterMinRelevance` | `3` | Min relevance to keep (0=disable) |
+| `retentionDays` | `90` | Auto-archive after N days |
+| `retentionMinStarred` | `true` | Keep starred prompts |
+| `retentionMinAnalyzed` | `true` | Keep analyzed prompts |
+| `retentionMinRelevance` | `3` | Archive prompts below this relevance |
+| `remoteUrl` | — | Remote ph server URL (or `PH_REMOTE_URL` env) |
+| `remoteApiKey` | — | Remote server API key |
+| `remoteLastPush` | — | Timestamp of last successful push |
+| `remoteLastPull` | — | Timestamp of last successful pull |
 
-### Search
+---
 
-```bash
-# Full-text search
-ph search "how to refactor"
+## 14. Architecture
 
-# Semantic search (vector similarity)
-ph search --semantic "refactoring patterns"
+```
+Hook/Import → ph log → prompts table (FTS5 indexed)
+                              ↓
+                    Background analysis (optional)
+                              ↓
+              ┌────────────────┴────────────────┐
+              ↓                                 ↓
+        memories (append-only,           project_summaries
+        with TTL)                        (1 row per project,
+                                          merged + deduped)
+              ↓                                 ↓
+        ph cleanup --retention            MCP tools read
+        → prompts_archive                 from here
 ```
 
-### Interactive TUI
+### File layout
 
-```bash
-ph browse
+```
+src/
+  cli.ts              # Entry point (~80 lines), switch dispatch
+  types.ts            # Core types (PromptEntry, MemoryEntry, ProjectSummary, etc.)
+  db/index.ts         # PhDB public SQLite adapter
+  db/semantic-index.ts # Vector encoding, storage, and nearest-neighbor search
+  context/index.ts    # Shared project-context retrieval and rendering
+  capture/index.ts    # Shared capture-record normalization
+  commands/           # One module per CLI command
+  analyzer/           # LLM analysis (role/tag/relevance/summary/insights)
+  embedding/          # Ollama embedding generation
+  filter/             # Capture-time filter pipeline
+  mcp/server.ts       # MCP stdio server
+  server/index.ts     # HTTP REST server (zero deps)
+  ui/                 # React/Ink TUI, including extracted filter policy and panel
+  importer/           # Gemini/Claude/OpenCode/Codex history importers
+hooks/                # Shell scripts and plugins for AI tools
 ```
 
-Available hotkeys inside the TUI:
-
-| Key | Action |
-|-----|--------|
-| `f` | Open filters panel |
-| `e` | Edit prompt metadata (tags, notes) |
-| `r` | Re-run selected prompt in your AI tool |
-| `y` | Copy prompt to clipboard |
-| `x` | Delete prompt from history |
+---
 
-### Export
+## 15. Importing Existing History
 
 ```bash
-# Export last 5 prompts as Markdown
-ph export --format md --limit 5 > prompts.md
-```
+# Import from Claude Code
+ph import claude --analyze
 
-### Database Maintenance
+# Import from Gemini CLI
+ph import gemini --filter
 
-```bash
-# Remove short or old prompts
-ph cleanup --min-length 20 --days 30
+# Import from OpenCode
+ph import opencode
 
-# Compact the database
-ph vacuum
+# Import from Codex CLI
+ph import codex --dry-run
+ph import codex
 
-# Dry-run to preview what would be removed
-ph cleanup --dry-run --days 60
+# Options:
+#   --analyze    run LLM analysis on imported prompts
+#   --filter     apply capture-time filters
+#   --dry-run    preview without importing
 ```
 
 ---
 
-## 6. Why Prompt History Matters
-
-Every interaction with an AI tool is a unit of intellectual work. A well-crafted prompt encodes context, intent, and engineering decisions that took time to develop. Without capture, that work is lost the moment the session closes.
-
-ph treats your prompt history as a first-class artifact: searchable, annotated, versioned with Git context, and available for re-use. Over time, your history becomes a personal knowledge base of how you think and work with AI tools.
+## 16. Versioning and Releases
 
-> **The problem:** Manually saving prompts takes time, breaks flow, and rarely happens consistently. Without structure, even saved prompts become unsearchable noise.
+Use Conventional Commits to describe changes: `feat:` requests a minor release,
+`fix:` requests a patch release, and `BREAKING CHANGE:` requests a major release.
+The GitHub Actions workflow runs `semantic-release` on pushes to `main`, updates
+release metadata, publishes to npm, and creates a GitHub release.
 
-> **The solution:** ph captures everything automatically via hooks, indexes it locally, and gives you semantic search so you can find what you need — even if you only remember the intent, not the exact wording.
+The Make targets `make release-patch`, `make release-minor`, and
+`make release-major` increment `package.json` and `package-lock.json` locally.
+They do not commit, tag, or publish. The automated release workflow determines
+the actual published version from commits since its most recent release tag.
 
 ---