@gi4nks/ph 1.5.0 → 1.7.0

package/docs/ph-manual.md

@@ -1,518 +1,520 @@
-# 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
-
----
-
-## 2. Architecture
-
-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.
-
-### Storage Layout
+In the TUI, `p` runs the selected prompt through one of the configured Wise analysis providers (same provider/model/URL settings shown by `ph config show`) and saves the response to history. `r` reruns the prompt with its original CLI tool.
 
-| Item | Default Path | Description |
-|------|-------------|-------------|
-| Database | `~/.prompt_history.db` | SQLite with FTS5 + vector embeddings |
-| Config | `~/.ph_config.json` | JSON config file (0o600 permissions) |
+### Key Features
 
-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.
+- **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
 
 ---
 
-## 3. The Hook System
-
-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.
-
-> **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.
-
-### How Hooks Work
+## 2. Installation
 
-Each supported AI CLI tool exposes a native hook mechanism:
+```bash
+# Via npm
+npm install -g @gi4nks/ph
 
-- **Claude Code** — provides a `Stop` hook, triggered after each agent session completes
-- **Gemini CLI** — provides an `AfterAgent` hook, triggered after each agent turn
+# From source
+git clone git@github.com:gi4nks/ph.git
+cd ph
+npm install
+npm run build
+npm link
+```
 
-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.
+### Quick config
 
-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.
+```bash
+ph config set background-analysis true   # auto-analyze after each capture
+ph config set analyze-provider ollama     # ollama (default), gemini, openrouter, or mlx-serve
+ph config set ollama-model llama3.1:latest
+```
 
 ---
 
-### Claude Code Hook
+## 3. Capture Modes
 
-#### How Claude Code delivers data
+### 3a. Hook mode (recommended)
 
-When the `Stop` hook fires, Claude Code sends a JSON object on stdin:
+AI CLI tools invoke `ph log` automatically after each interaction.
 
-```json
-{
-  "session_id": "abc123...",
-  "transcript_path": "/path/to/session.jsonl"
-}
+**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 }] }] }
 ```
 
-The transcript is a JSONL file — one JSON object per line — containing the full session history. Each line is one of:
-
-| 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 |
-
-#### What the hook script does
-
-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
-
-#### Hook installation — Claude Code
-
+**Gemini CLI** — `hooks/gemini/ph-hook.sh`:
 ```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
-          }
-        ]
-      }
-    ]
-  }
-}
+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" }] }] }
 ```
 
----
-
-### Gemini CLI Hook
+**OpenCode** — plugin at `hooks/opencode/ph-plugin.ts`:
+```bash
+./hooks/opencode/install.sh   # global install
+```
 
-#### How Gemini CLI delivers data
+**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`.
 
-Gemini CLI's `AfterAgent` hook is simpler: it delivers the prompt and response directly in the stdin payload, with no transcript file to parse:
+### 3b. Wrapper mode
 
-```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
+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"
 ```
 
-#### What the hook script does
-
-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
-
-#### Hook installation — Gemini CLI
+### 3c. Direct log
 
 ```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 log --tool claude --prompt "your prompt" --response "response text"
+echo '{"tool":"claude","prompt":"hi","response":"hello"}' | ph log --stdin
 ```
 
 ---
 
-### 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.
-
-#### How the plugin captures data
-
-The plugin registers two hooks inside OpenCode's runtime:
-
-| 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. |
-
-**Data flow:**
+## 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
 
 ```
-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
+-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
 ```
 
-#### Hook installation — OpenCode
-
-OpenCode loads plugins from two directories:
-- `~/.config/opencode/plugins/` — global (all projects)
-- `.opencode/plugins/` — per-project
+### Context options
 
-**Option A: Quick install (global)**
-
-```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
 ```
-
-Or use the install script:
-
-```bash
-./hooks/opencode/install.sh              # global (default)
-./hooks/opencode/install.sh --project    # current project only
+--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
 ```
 
-**Option B: Manual copy**
+### Sessions options
 
-```bash
-cp hooks/opencode/ph-plugin.ts ~/.config/opencode/plugins/
 ```
-
-The plugin is automatically loaded on the next OpenCode startup. No config changes needed — Bun handles TypeScript natively.
-
-**Verify:**
-
-```bash
-# Start OpenCode — the plugin loads silently
-opencode
-
-# Check that prompts are being captured
-ph search --tool opencode --limit 3
+--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
 ```
 
-**Uninstall:**
+### Cluster options
 
-```bash
-rm ~/.config/opencode/plugins/ph-plugin.ts
+```
+-k <number>           Number of clusters (default 5)
+--limit <n>           Max prompts per cluster to show (default 3)
 ```
 
 ---
 
-### Hook Comparison
+## 5. TUI Keybindings
 
-| 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 |
+| 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)
 
 ---
 
-## 4. Installation
+## 6. Project Memory System
 
-### From Source
+ph maintains two levels of per-project knowledge:
 
-```bash
-git clone git@github.com:gi4nks/ph.git
-cd ph
-npm install
-make build
-make install    # installs the global 'ph' symlink
-```
+### 6a. `project_summaries` (curated, 1 row per project)
 
-### Via npm
+Accumulated knowledge with deduped insights and decisions. Updated on every analysis. Primary source for MCP tools.
 
 ```bash
-# Install globally:
-npm install -g @gi4nks/ph
+# View accumulated project knowledge
+ph context --project myproject
+
+# Via MCP (for AI agents)
+# get_project_summary(project: "myproject")
 ```
 
-### Initial Configuration
+### 6b. `memories` (append-only timeline)
 
-```bash
-# Set your Gemini API key (optional — Ollama works without it)
-ph config set gemini-api-key "YOUR_KEY"
+Full chronological history of every analysis run. Preserved for detailed audit.
 
-# Choose your analysis provider
-ph config set analyze-provider ollama   # default, fully local
-# ph config set analyze-provider gemini  # cloud alternative
+### Memory migration
 
-# Enable background analysis
-ph config set background-analysis true
+If you have existing data from before the evolution phases:
 
-# Optional: move the database to a custom location
-ph config set db-path "/path/to/your/custom.db"
+```bash
+ph memory-migrate   # one-time: merge all memories into project_summaries
 ```
 
 ---
 
-## 5. Usage
+## 7. Retention & Archiving
 
-### Search
+Configurable auto-archiving to keep the database lean:
 
 ```bash
-# Full-text search
-ph search "how to refactor"
+# 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
 
-# Semantic search (vector similarity)
-ph search --semantic "refactoring patterns"
-```
+# Run retention cleanup
+ph cleanup --retention                    # archive matching prompts
+ph cleanup --retention --dry-run          # preview only
 
-### Interactive TUI
+# Search archived prompts
+ph search --archive
 
-```bash
-ph browse
+# Auto-purge: entries older than 2x retentionDays are deleted during cleanup
 ```
 
-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 |
+## 8. Background Analysis
 
-### Export
+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
-# Export last 5 prompts as Markdown
-ph export --format md --limit 5 > prompts.md
+ph config set background-analysis true
 ```
 
-### Database Maintenance
+Analysis uses Ollama by default (requires `ollama serve` running). Configure:
 
 ```bash
-# Remove short or old prompts
-ph cleanup --min-length 20 --days 30
+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
+```
 
-# Compact the database
-ph vacuum
+OpenRouter and MLX-Serve generation use `@gi4nks/wise`:
 
-# Dry-run to preview what would be removed
-ph cleanup --dry-run --days 60
+```bash
+# OpenRouter: credentials stay in the environment; model IDs keep provider/model.
+export OPENROUTER_API_KEY="your_openrouter_api_key"
+ph models openrouter
+ph config set openrouter-api-key  # hidden prompt; or keep using the environment
+ph config set analyze-provider openrouter
+ph config set openrouter-model "provider/model-id"
+ph config show                    # provider settings with credentials redacted
+ph analyze
+
+# MLX-Serve on Parmenide: open this tunnel in a separate terminal.
+ssh -N -L 11234:127.0.0.1:11234 parmenide
 ```
 
----
+```bash
+# In the terminal where you run ph:
+ph models mlx-serve
+ph config set analyze-provider mlx-serve
+ph config set mlx-serve-model "exact-model-id-from-server"
+ph analyze
+```
 
-## 6. Why Prompt History Matters
+MLX-Serve defaults to `http://127.0.0.1:11234/v1`. Override it with
+`MLX_SERVE_BASE_URL` or `ph config set mlx-serve-url <url>`. Set
+`MLX_SERVE_API_KEY` if the server requires auth; `GLB_OMLX_API_KEY` is also
+accepted for existing setups. Alternatively run `ph config set mlx-serve-api-key`
+to enter it without echoing it in the terminal. `ph config show` redacts
+credentials. `ph models mlx-serve` marks entries `[loaded]` or `[unloaded]`.
 
-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.
+## 9. MCP Server
 
-> **The problem:** Manually saving prompts takes time, breaks flow, and rarely happens consistently. Without structure, even saved prompts become unsearchable noise.
+ph exposes an MCP (Model Context Protocol) server over stdio for AI agents:
 
-> **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.
+```bash
+ph mcp
+```
 
----
+### 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 |
 
 ---
 
-## 7. Remote Server Setup
-
-ph can act as a central sync hub for prompt history across multiple machines.
+## 10. HTTP Server & Remote Sync
 
-### Server Installation
+Share prompt history across machines:
 
 ```bash
-# Install globally
-sudo npm install -g @gi4nks/ph
-
-# Verify
-ph --help
+# 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
 ```
 
-### Ubuntu (systemd service)
+Every `ph log` auto-pushes to remote if configured (fire-and-forget, never blocks).
 
-Create `/etc/systemd/system/ph.service`:
+---
 
-```ini
-[Unit]
-Description=ph remote sync server
-After=network.target
+## 11. Database
 
-[Service]
-Type=simple
-ExecStart=<path-to-ph> server --port 3001 --host 0.0.0.0
-Restart=always
-RestartSec=5
-User=<your-user>
-Environment=NODE_ENV=production
-StandardOutput=append:/var/log/ph-server.log
-StandardError=append:/var/log/ph-server.log
+**Location:** `~/.prompt_history.db` (configurable via `ph config set db-path`)
 
-[Install]
-WantedBy=multi-user.target
-```
+**Tables:**
 
-Replace `<path-to-ph>` with the output of `which ph` on the server, and `<your-user>` with the user running the service.
+| 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) |
 
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now ph.service
-sudo systemctl status ph.service
-sudo ufw allow 3001/tcp   # if firewall is enabled
-```
-
-### macOS (launchd)
-
-Create `~/Library/LaunchAgents/com.gi4nks.ph.plist`:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key>
-    <string>com.gi4nks.ph</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>/usr/local/bin/ph</string>
-        <string>server</string>
-        <string>--port</string>
-        <string>3001</string>
-        <string>--host</string>
-        <string>0.0.0.0</string>
-    </array>
-    <key>RunAtLoad</key>
-    <true/>
-    <key>KeepAlive</key>
-    <true/>
-    <key>StandardOutPath</key>
-    <string>/tmp/ph-server.log</string>
-    <key>StandardErrorPath</key>
-    <string>/tmp/ph-server.err</string>
-</dict>
-</plist>
-```
+**Maintenance:**
 
 ```bash
-launchctl load ~/Library/LaunchAgents/com.gi4nks.ph.plist
+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
 ```
 
-### Client Setup
+---
 
-```bash
-# Configure remote server URL
-ph config set remote-url http://<server-ip>:3001
-# Or via env var (takes precedence)
-export PH_REMOTE_URL=http://<server-ip>:3001
-
-# Sync commands
-ph remote push    # send unsynced local prompts to server
-ph remote pull    # fetch remote prompts since last pull
-ph remote status  # show sync state
-```
+## 12. Filter Pipeline
 
-After `ph remote-url` is configured, every `ph log` automatically does a background push to the server (fire-and-forget, never blocks).
+Before saving, ph filters out:
 
-### Logs
+- 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)
 
-```bash
-# systemd
-sudo journalctl -u ph.service -f
+Configure:
 
-# launchd
-cat /tmp/ph-server.log
+```bash
+ph config set filter-min-length 20
+ph config set filter-min-relevance 3
 ```
 
 ---
 
-## 8. Release Process
+## 13. Configuration (`~/.ph_config.json`)
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `dbPath` | `~/.prompt_history.db` | SQLite database path |
+| `analyzeProvider` | `ollama` | LLM provider: `ollama`, `gemini`, `openrouter`, or `mlx-serve` |
+| `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 |
+| `openrouterModel` | — | Exact OpenRouter model ID |
+| `openrouterUrl` | `https://openrouter.ai/api/v1` | OpenRouter-compatible API root |
+| `mlxServeModel` | — | Exact MLX-Serve model ID |
+| `mlxServeUrl` | `http://127.0.0.1:11234/v1` | MLX-Serve API root (Parmenide SSH tunnel by default) |
+| `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 |
+
+Provider API credentials are environment-only: `OPENROUTER_API_KEY` and
+`MLX_SERVE_API_KEY` (`GLB_OMLX_API_KEY` is a fallback). They are not written to
+`~/.ph_config.json`.
+
+---
+
+## 14. Architecture
 
-Releases are fully automated via **semantic-release** using conventional commits.
+```
+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
+```
 
-### How it works
+### File layout
 
-1. All commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
+```
+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
+```
 
-   ```
-   feat: add new feature          → minor release (1.x.0)
-   fix: resolve bug               → patch release (1.0.x)
-   chore: bump deps               → no release
-   BREAKING CHANGE: ...           → major release (x.0.0)
-   ```
+---
 
-2. Push to `main` triggers GitHub Actions workflow `.github/workflows/release.yml`
+## 15. Importing Existing History
 
-3. The workflow runs:
-   - `actions/checkout@v4` with full git history (`fetch-depth: 0`)
-   - `actions/setup-node@v4` with Node 22
-   - `npm ci` — clean install
-   - `npm run build` — tsup bundle
-   - `npx semantic-release` — analyzes commits, bumps version, updates CHANGELOG.md, creates git tag, publishes to npm
+```bash
+# Import from Claude Code
+ph import claude --analyze
 
-### npm publish details
+# Import from Gemini CLI
+ph import gemini --filter
 
-- **OIDC Trusted Publishing**: Package is signed with provenance attestation via GitHub Actions OIDC token
-- **Publisher identity**: `GitHub Actions <npm-oidc-no-reply@github.com>`
-- **Registry**: `https://registry.npmjs.org/`
-- **Access**: public
+# Import from OpenCode
+ph import opencode
 
-### Verify provenance
+# Import from Codex CLI
+ph import codex --dry-run
+ph import codex
 
-```bash
-npm audit signatures
+# Options:
+#   --analyze    run LLM analysis on imported prompts
+#   --filter     apply capture-time filters
+#   --dry-run    preview without importing
 ```
 
-### Manual release (emergency)
+---
+
+## 16. Versioning and Releases
 
-Create a tag manually and push:
+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.
 
-```bash
-git tag v1.2.3
-git push origin v1.2.3
-```
+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.
 
 ---