@gi4nks/ph 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# [1.8.0](https://github.com/gi4nks/ph/compare/v1.7.0...v1.8.0) (2026-10-24)
+
+
+### Bug Fixes
+
+* harden PH capture, recall, and synchronization ([0e65743](https://github.com/gi4nks/ph/commit/0e657438bc2e59f2dcf14dd73e02882c29bfa390))
+
+
+### Features
+
+* add operational memory and consolidate architecture ([39aeae5](https://github.com/gi4nks/ph/commit/39aeae507a6bab93c8d1ff49555b82fb7fc9fc37))
+* make PH capture setup automatic ([35aad32](https://github.com/gi4nks/ph/commit/35aad321730dd8f1b04665af890e60e8c75a56e9))
+* simplify PH command-line workflow ([05b5ea7](https://github.com/gi4nks/ph/commit/05b5ea7202d55a05c277eafc6e2b51b1913f5063))
+
+# [1.7.0](https://github.com/gi4nks/ph/compare/v1.6.0...v1.7.0) (2026-10-18)
+
+
+### Features
+
+* integrate Wise providers in ph ([4f8094e](https://github.com/gi4nks/ph/commit/4f8094e506430f43a96eaca299c6fc85a65870a9))
+
 # [1.6.0](https://github.com/gi4nks/ph/compare/v1.5.0...v1.6.0) (2026-10-09)
 
 
@@ -48,7 +69,7 @@ All notable changes to this project will be documented in this file. See [standa
 * **config:** `remote-url`, `remote-api-key` config keys + `PH_REMOTE_URL` env var support
 * **opencode:** native importer (`ph import opencode`) + real-time plugin hook
 
-### (prima di continuare con il commit fammi vedere se ti piace la situazione ) vabene?  
+### Before continuing with the commit, show me the current state and check that it looks good.
 
 
 ## [1.3.0](https://github.com/gi4nks/ph/compare/v1.2.0...v1.3.0) (2026-04-12)

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Gianluca
+Copyright (c) 2026 gi4nks
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,12 +5,9 @@
 ## What it does
 
 - 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.
+- Searches prompts and responses, then retrieves task-relevant project context through one command.
+- Reviews recent work and saves durable project decisions only after explicit approval.
+- Keeps data local by default; hooks and MCP are available for automatic capture and agent access.
 
 ## Install
 
@@ -30,25 +27,33 @@ npm run build
 npm link
 ```
 
-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.
+Requires Node.js 22 or later (the Wise/AI SDK provider stack requires Node 22). Ollama is optional; it is used for local analysis and semantic embeddings. Gemini can be used for analysis when configured.
 
 ## Quick start
 
 ```bash
-# Capture a prompt by wrapping an installed AI CLI tool
-ph claude "explain goroutines"
+# Connect PH once to the AI CLIs you use
+ph setup
+
+# Then use Claude Code, Codex, or Gemini CLI normally. Completed exchanges
+# are captured in the background by each tool's native hook.
+claude
+codex
 
 # Search prompt history
 ph search "goroutines"
-ph search --semantic "concurrency patterns"
-
-# Open the interactive browser
-ph browse
+ph show 42                       # Full prompt, response, and available analysis
+# Search all projects when needed
+ph search --all "goroutines"
 
 # Add a record directly
 ph log --tool claude --prompt "Explain this function" --response "It parses..."
 ```
 
+`ph setup` detects installed Claude Code, Codex CLI, Gemini CLI, and OpenCode integrations, then installs capture hooks while preserving existing settings. Pass tool names to select explicitly (`ph setup codex claude`). It is safe to run again. Use `ph <tool>` as a wrapper if you prefer not to install hooks.
+
+`ph search "query"` searches the current project and shows five matches, ranked by text relevance. Use `--limit <n>` for more results or `--all` to search across projects. Codex hook captures use the active CLI working directory so new conversations get associated with the project where Codex was launched.
+
 ## Capture history
 
 ### Wrapper
@@ -85,7 +90,7 @@ 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).
+Codex is also available through wrapper mode: `ph codex exec "prompt"`. See [Codex hook setup](hooks/codex/README.md).
 
 ## Search and project context
 
@@ -93,15 +98,27 @@ Codex is also available through wrapper and context-injected modes: `ph codex ex
 ph search --tool claude --role debug --since 2026-01-01
 ph search --semantic "How did I configure SQLite migrations?"
 ph search --archive "database migration"
+ph show 42 --json                # Machine-readable interaction detail
+ph show 42                       # full prompt, response, and available analysis
+ph show 42 --json                # machine-readable detail
 
 # 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
+
+# Retrieve a task brief with relevant history (read-only)
+ph context "add Wise provider" --limit 5 --budget 3500
+
+# Review recent work and explicitly promote useful knowledge (defaults to 3h)
+ph close
+ph close --from 1670 --to 1682 --dry-run
 ```
 
-`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.
+`ph context "task"` retrieves task-specific history when you want to supply it explicitly. `ph close` is an optional review workflow for promoting durable knowledge; it is not required for capture or search. `ph prepare` remains a compatibility alias for `ph context`.
+
+Running `ph` prints the short setup-first workflow; it does not open a TUI. `ph browse` remains as a compatibility alias for listing recent interactions. `ph help --all` lists maintenance and integration commands.
 
 ## Project memory and analysis
 
@@ -121,7 +138,41 @@ 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.
+For OpenRouter, use the environment or enter the key through ph's hidden prompt, then select an exact model ID:
+
+```bash
+export OPENROUTER_API_KEY="your_openrouter_api_key"
+ph models openrouter
+ph config set openrouter-api-key        # prompts securely; stored in ~/.ph_config.json
+ph config set analyze-provider openrouter
+ph config set openrouter-model "provider/model-id"
+ph config show                         # shows active settings, redacts keys
+ph analyze
+```
+
+For MLX-Serve on Parmenide, open an SSH tunnel to its API port (11234 by default),
+then select an ID returned by the server. Keep the tunnel running in a separate terminal:
+
+```bash
+# Terminal 1
+ssh -N -L 11234:127.0.0.1:11234 parmenide
+```
+
+```bash
+# Terminal 2
+ph models mlx-serve
+ph config set analyze-provider mlx-serve
+ph config set mlx-serve-model "exact-model-id-from-server"
+ph analyze
+```
+
+The MLX-Serve URL defaults to `http://127.0.0.1:11234/v1`; override it with
+`MLX_SERVE_BASE_URL` or `ph config set mlx-serve-url <url>`. If the server requires
+authentication, set `MLX_SERVE_API_KEY` or run `ph config set mlx-serve-api-key`
+for a hidden prompt. `ph config show` redacts credentials. The model catalog
+marks installed models as `[loaded]` or `[unloaded]`.
+
+Automatic analysis enriches each interaction with classification, summary, insights, and decisions; these derived fields are searchable and visible with `ph show`. Analysis does not modify active project memories or summaries. Only approved `ph close` proposals and MCP `save_decision` promote knowledge. Existing memories remain available. Task context retrieval is shared by `ph context`, `ph chat`, and MCP knowledge checks, with a labeled recent-history fallback.
 
 ## MCP integration
 
@@ -151,7 +202,7 @@ ph remote pull
 ph remote status
 ```
 
-`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.
+`PH_REMOTE_URL` overrides the configured remote URL. The server refuses to start until `remote-api-key` is configured, and every client must provide the same key. It listens on loopback by default; use an explicit `--host` only for a protected network interface and use TLS when traffic crosses an untrusted network. `/health` is public and returns status only. Resumable ID cursors are scoped to both the remote target and local database, and byte-bounded subpages stay below the server's 32 MiB request cap. A bulk push pauses before a live wrapper interaction until its response is saved. `ph log` and both wrapper modes push after capture when a remote is configured; the request is bounded to five seconds so an unavailable server cannot hang the command indefinitely. An invalid remote URL does not prevent local capture or launching the wrapped tool. Current limitation: a remote database replacement behind the same URL is not detected, and last-push/pull status timestamps are shared across targets.
 
 ## Configuration and storage
 
@@ -160,15 +211,24 @@ Configuration is stored in `~/.ph_config.json`; the database defaults to `~/.pro
 | Setting | Default | Purpose |
 |---|---|---|
 | `db-path` | `~/.prompt_history.db` | SQLite database location |
-| `analyze-provider` | `ollama` | Analysis provider: `ollama` or `gemini` |
+| `analyze-provider` | `ollama` | Analysis provider: `ollama`, `gemini`, `openrouter`, or `mlx-serve` |
 | `ollama-url` | `http://localhost:11434` | Ollama endpoint |
 | `ollama-model` | `llama3.1:latest` | Analysis model |
+| `openrouter-model` | unset | Exact OpenRouter model ID, including its provider prefix |
+| `openrouter-url` | `https://openrouter.ai/api/v1` | OpenRouter-compatible API root |
+| `mlx-serve-model` | unset | Exact model ID returned by MLX-Serve |
+| `mlx-serve-url` | `http://127.0.0.1:11234/v1` | MLX-Serve API root, normally the Parmenide SSH tunnel |
 | `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 |
+| `remote-api-key` | unset | Required to start the HTTP server; sent by remote clients |
+
+Provider credentials can be stored in `~/.ph_config.json` through the hidden
+`ph config set <provider>-api-key` prompts or supplied through environment
+variables. Environment values take precedence; MLX-Serve also accepts the
+existing `GLB_OMLX_API_KEY` variable.
 
 ## Development