@gi4nks/ph 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.6.0](https://github.com/gi4nks/ph/compare/v1.5.0...v1.6.0) (2026-10-09)
+
+
+### Features
+
+* publish current ph snapshot against GitHub main ([943ced9](https://github.com/gi4nks/ph/commit/943ced97aa63e1c183ac029ae76833583559ce98))
+
 # [1.4.0](https://github.com/gi4nks/ph/compare/v1.3.2...v1.4.0) (2026-05-16)
 
 

package/README.md

@@ -1,104 +1,193 @@
-# ph — Prompt History & Analysis Tool
+# ph — Prompt History and Project Memory
 
-`ph` is a transparent observability layer for AI CLI tools. It captures every prompt+response into a local SQLite database with full-text and semantic search, automatic LLM analysis, interactive TUI browser, MCP server, and optional remote sync for cross-laptop memory sharing.
+`ph` captures prompt and response history from AI command-line tools and makes it searchable from the terminal or available to agents through MCP. It stores data in a local SQLite database and can optionally analyze, archive, or synchronize that data.
 
-## Key Features
+## What it does
 
-- 📥 **Automatic Capture**: Wrapper mode (`ph claude "..."`), hook mode (Claude/Gemini/OpenCode), or direct (`ph log`).
-- 🔍 **Advanced Search**: FTS5 full-text search and sqlite-vec semantic search with rich filters (tool, project, role, tag, date range).
-- 🧠 **Background Analysis**: Automatic prompt classification (role, tags, relevance) via Ollama or Gemini — builds project-level memories.
-- 🖥️ **Interactive TUI**: Full-screen browser with filter panel, preview pane, project memory viewer, and session grouping.
-- 🔌 **MCP Server**: Exposes prompt history and project knowledge as MCP tools (`search_prompts`, `get_prompt`, `search_project_memory`, etc.) — usable by any MCP client including OpenCode.
-- 🌐 **HTTP Server & Remote Sync**: `ph server` starts a REST API. `ph remote push|pull` syncs prompts across laptops. Background push after each `ph log`.
-- 🔗 **OpenCode Plugin**: Native plugin for real-time capture via OpenCode hooks.
+- Captures conversations through a transparent command wrapper, native hooks, direct logging, or history import.
+- Searches prompts and responses with SQLite FTS5, or searches by semantic similarity with Ollama embeddings and sqlite-vec.
+- Groups records by project, tool, language, role, tags, time, and quality metadata.
+- Builds project summaries and an append-only analysis history with optional Ollama or Gemini analysis.
+- Exposes prompt history and project knowledge through an MCP server over stdio.
+- Provides an interactive terminal browser for filtering, reviewing, editing metadata, starring, exporting, and rerunning prompts.
+- Supports optional HTTP sync between a local database and a remote `ph` server.
 
-## Installation
+## Install
+
+Install from npm:
 
 ```bash
-# Clone and local build
-git clone git@github.com:gi4nks/ph.git
-cd ph
-npm install
-make build
-make install
+npm install -g @gi4nks/ph
 ```
 
-Or install from npm:
+Or build from source:
+
 ```bash
-npm install -g @gi4nks/ph
+git clone https://github.com/gi4nks/ph.git
+cd ph
+npm ci
+npm run build
+npm link
 ```
 
-## Quick Start
+Requires Node.js 20 or later. Ollama is optional; it is used for local analysis and semantic embeddings. Gemini can be used for analysis when configured.
+
+## Quick start
 
 ```bash
-# Wrap an AI tool
+# Capture a prompt by wrapping an installed AI CLI tool
 ph claude "explain goroutines"
 
-# Search history
+# Search prompt history
 ph search "goroutines"
 ph search --semantic "concurrency patterns"
-ph search --tool claude --role debug --since 2026-01-01
 
-# Browse with TUI
+# Open the interactive browser
 ph browse
 
-# Start HTTP server for remote sync
-ph server --port 3001
+# Add a record directly
+ph log --tool claude --prompt "Explain this function" --response "It parses..."
+```
+
+## Capture history
+
+### Wrapper
+
+Run an installed tool through `ph` to record its prompt and response:
+
+```bash
+ph claude "explain goroutines"
+ph --ph-role debug --ph-tag auth claude "fix JWT expiration"
+```
+
+Interactive wrapper mode is available when the wrapped tool is run without command-line prompt arguments.
+
+### Native hooks
+
+Hooks capture completed exchanges without changing the tool invocation:
+
+- Claude Code: [hooks/claude/ph-hook.sh](hooks/claude/ph-hook.sh)
+- Codex CLI: [hooks/codex/ph-hook.sh](hooks/codex/ph-hook.sh)
+- Gemini CLI: [hooks/gemini/ph-hook.sh](hooks/gemini/ph-hook.sh)
+- OpenCode: [hooks/opencode/ph-plugin.ts](hooks/opencode/ph-plugin.ts)
+
+See [docs/hooks.md](docs/hooks.md) for the integration overview and [docs/ph-manual.md](docs/ph-manual.md) for setup details.
+
+### Direct logging and history import
+
+```bash
+ph log --tool claude --prompt "Explain this function" --response "It parses..."
+echo '{"tool":"claude","prompt":"Explain this function","response":"It parses..."}' | ph log --stdin
+
+ph import claude --dry-run
+ph import gemini --filter
+ph import opencode
+ph import codex --dry-run
+```
+
+Codex is also available through wrapper and context-injected modes: `ph codex exec "prompt"` and `ph chat codex exec "prompt"`. See [Codex hook setup](hooks/codex/README.md).
+
+## Search and project context
 
-# Sync with another machine
-export PH_REMOTE_URL=http://my-server:3001
-ph remote push   # push local prompts to server
-ph remote pull   # pull remote prompts into local DB
+```bash
+ph search --tool claude --role debug --since 2026-01-01
+ph search --semantic "How did I configure SQLite migrations?"
+ph search --archive "database migration"
+
+# Retrieve project knowledge and related prompts for the current directory
+ph context "How are database migrations handled?"
+
+# Limit the output to project summaries and memories
+ph context --memories-only --project ph
 ```
 
-## Configuration
+`ph context`, `ph chat`, and MCP project-context tools use shared retrieval and formatting. Semantic results are scoped to the requested project before the result limit is applied.
+
+## Project memory and analysis
 
-Config file at `~/.ph_config.json`:
+Enable background analysis after each capture:
 
 ```bash
-ph config set analyze-provider ollama    # or 'gemini' (default: ollama)
-ph config set background-analysis true    # auto-analyze after each log
-ph config set remote-url http://server:3001  # remote sync target
+ph config set background-analysis true
+ph config set analyze-provider ollama
+ph config set ollama-model llama3.1:latest
+ph config set ollama-embed-model nomic-embed-text-v2-moe
 ```
 
-Environment variable `PH_REMOTE_URL` takes precedence over config.
+For Gemini analysis:
+
+```bash
+ph config set analyze-provider gemini
+ph config set gemini-api-key "$GEMINI_API_KEY"
+```
+
+Project summaries merge deduplicated insights and technical decisions. Individual analysis results remain in an append-only memory timeline. Analysis and embeddings require the corresponding provider to be available; basic capture and full-text search do not.
+
+## MCP integration
+
+Start the stdio server with:
 
-## Storage
+```bash
+ph mcp
+```
 
-| Item | Default Path | Description |
-|------|--------------|-------------|
-| Database | `~/.prompt_history.db` | SQLite with FTS5 + sqlite-vec |
-| Config | `~/.ph_config.json` | JSON with 0o600 permissions |
+The server exposes tools for prompt search and lookup, project context and summaries, project timelines, knowledge checks, and saving decisions. Configure `ph mcp` as a stdio server in the MCP client you use.
 
-## Architecture
+## Remote sync
 
+Run an HTTP server on the machine that will store the shared database:
+
+```bash
+ph config set remote-api-key "$PH_REMOTE_API_KEY"
+ph server --host 127.0.0.1 --port 3001
 ```
-Capture modes: wrapper → hook → direct → OpenCode plugin
-     |
-     v
-Local SQLite (FTS5 + vec0 + memories)
-     |
-     ├── MCP server (stdio)  →  OpenCode / any MCP client
-     ├── HTTP server (REST)  →  remote ph instances
-     └── Background analysis →  memories table (append-only per project)
+
+Set a client remote URL and synchronize:
+
+```bash
+ph config set remote-url http://127.0.0.1:3001
+ph remote push
+ph remote pull
+ph remote status
 ```
 
-## Hooks
+`PH_REMOTE_URL` overrides the configured remote URL. If `remote-api-key` is set on the server, clients must also provide that key. Use a private network or a TLS-terminating proxy when connecting across machines. Each `ph log` performs a non-blocking push when a remote is configured.
 
-Hooks in `hooks/` integrate with AI CLI tools natively:
+## Configuration and storage
 
-- **Claude Code**: `hooks/claude/ph-hook.sh` — Stop hook
-- **Gemini CLI**: `hooks/gemini/ph-hook.sh` — AfterAgent hook
-- **OpenCode**: `hooks/opencode/ph-plugin.ts` — native plugin (captures streaming responses)
+Configuration is stored in `~/.ph_config.json`; the database defaults to `~/.prompt_history.db`.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `db-path` | `~/.prompt_history.db` | SQLite database location |
+| `analyze-provider` | `ollama` | Analysis provider: `ollama` or `gemini` |
+| `ollama-url` | `http://localhost:11434` | Ollama endpoint |
+| `ollama-model` | `llama3.1:latest` | Analysis model |
+| `ollama-embed-model` | `nomic-embed-text-v2-moe` | Embedding model; current schema expects 768 dimensions |
+| `background-analysis` | `false` | Analyze newly captured prompts asynchronously |
+| `filter-min-length` | `15` | Minimum prompt length accepted by filtering |
+| `filter-min-relevance` | `3` | Relevance threshold for filtered imports/analysis workflows |
+| `remote-url` | unset | Remote `ph` server; `PH_REMOTE_URL` takes precedence |
+| `remote-api-key` | unset | Optional server authentication key |
 
 ## Development
 
 ```bash
-make build    # tsup build
-make test     # vitest
-make lint     # eslint
+npm ci
+npm test
+npm run lint
+npx tsc --noEmit
+npm run build
+```
+
+Run the optional model-backed retrieval evaluation when an Ollama embedding endpoint is available:
+
+```bash
+npm run eval:retrieval
 ```
 
+See [docs/ph-manual.md](docs/ph-manual.md), [docs/specs/SPEC-INDEX.md](docs/specs/SPEC-INDEX.md), and [docs/ph-analysis.html](docs/ph-analysis.html) for the user guide, behavior specifications, and architecture report.
+
 ## License
 
 MIT