@eltonssouza/development-utility-kit 1.0.0

package/dashboard/public/content/docs/honcho-memory.en.md

@@ -0,0 +1,394 @@
+# Honcho Memory
+
+Persistent cross-session memory for Claude Code, anchored on **Honcho v3 self-hosted**. Memories survive across sessions, projects, and machines. When relevant, they are injected automatically into the system prompt of every turn through the `[HONCHO MEMORY]` block, so the user does not have to re-explain preferences.
+
+The integration runs as a pair of Claude Code hooks (`UserPromptSubmit` and `Stop`) and degrades gracefully: if the Honcho server is offline, the hook times out, returns exit 0, and Claude proceeds without the memory block. The main flow never blocks.
+
+Audience: Java/Angular developers who want the assistant to "remember" style rules, stack decisions, and feature context without reopening documents every session.
+
+---
+
+## Flow overview
+
+```
+user prompt
+   |
+   v
+UserPromptSubmit hook (on-prompt-submit.js)
+   |
+   |-- trigger detected? ("lembra que", "remember that", "never ...", "always ...")
+   |     |
+   |     v
+   |   SAVE explicit (POST /v3/.../messages, metadata.type = "explicit")
+   |
+   |-- hybrid search in Promise.all (timeoutMs default = 450ms)
+   |     |
+   |     |-- peer-scoped     (POST /peers/{peer}/search)  -> cross-project explicit + inferred
+   |     |-- session-scoped  (POST /sessions/{id}/messages/list) -> project-context
+   |
+   |-- merge by relevance, cap topN + 2000 chars
+   |
+   v
+stdout: [HONCHO MEMORY] ... [/HONCHO MEMORY]   ->   injected into system prompt
+   |
+   v
+Claude responds
+   |
+   v
+Stop hook (on-stop.js)
+   |
+   v
+extracts feature/sprint from CLAUDE.md + git log -3
+   |
+   v
+SAVE project-context (POST /v3/.../messages, metadata.type = "project-context")
+```
+
+Hooks are registered in `~/.claude/settings.json` (global), pointing to `C:/development/tools/development-utility-kit/.claude/skills/honcho-memory/hooks/`. Forward-slash paths — accepted by the Claude Code hook runner on Windows.
+
+---
+
+## Memory types
+
+The `type` metadata on every message saved to Honcho controls scope, source and visibility.
+
+| Type | Scope | Source | When it is created |
+|---|---|---|---|
+| `explicit` | Peer (cross-project) | User | Triggered by verbal patterns ("lembra que", "remember that", "memoriza", "never ...", "always ...") |
+| `inferred` | Peer (cross-project) | Automatic hook (v2) | **Disabled by default in v1** — stub for `PLAN_honcho-inference.md`. When `inferenceEnabled: true`, `on-stop.js` only writes `HONCHO_INFO` to stderr and proceeds without inference |
+| `project-context` | Session (1 per CWD) | `Stop` hook | At the end of each turn, extracts active feature/sprint from `CLAUDE.md` + last 3 commits |
+
+The `session ID` is derived deterministically: `sha256(CWD)[:16]`. Each directory is a unique bucket and never rotates — every `project-context` memory for `C:/dev/source/projects/foo/` accumulates in the same session indefinitely.
+
+---
+
+## Automatic triggers
+
+Five patterns in the user prompt trigger an **immediate explicit save**, before any search. The save happens with `metadata.type = "explicit"` and `metadata.source = "user"`.
+
+| Pattern | Language | Example |
+|---|---|---|
+| `lembra que` | PT | "lembra que prefiro records imutáveis em DTOs Java" |
+| `remember that` | EN | "remember that I prefer immutable records" |
+| `memoriza` | PT | "memoriza: usar OnPush em todos os componentes Angular" |
+| `never ` (start of line) | EN | "never use var in TypeScript" |
+| `always ` (start of line) | EN | "always add JSDoc to public methods" |
+
+Detection is case-insensitive. Matching is done against `prompt.toLowerCase()`.
+
+Trigger-saved memories are **peer-scoped** — they surface in searches from any project that uses the same `peerName` in `config.json`.
+
+---
+
+## CLI subcommands
+
+The CLI lives at `.claude/skills/honcho-memory/scripts/cli.js` and runs via `bun`. The subcommands are also what the user invokes in chat (the skill detects the `/honcho <verb>` pattern and routes to the script).
+
+```bash
+bun run .claude/skills/honcho-memory/scripts/cli.js <subcommand> [args]
+```
+
+### `/honcho save <text>`
+
+Saves an explicit memory immediately. Prints the message ID.
+
+```text
+$ /honcho save "prefer Testcontainers in integration, never H2"
+saved: msg_01HXY7K9AB...
+type: explicit
+peer: elton
+```
+
+### `/honcho search <query>`
+
+Peer-scoped semantic search. Returns top-N (default 5) relevant memories. Soft-deleted memories are excluded.
+
+```text
+$ /honcho search "java DTO"
+1. [explicit | 2026-05-12] Prefer immutable records for DTOs in Java
+2. [explicit | 2026-04-30] Never expose JPA entities directly through the API
+3. [project-context | 2026-05-20] Sprint 3 — refactor backend DTOs to records
+```
+
+### `/honcho list`
+
+Lists every memory in the current session (filtered by `sha256(CWD)[:16]`). Soft-deleted memories do not appear.
+
+```text
+$ /honcho list
+session: a1b2c3d4e5f60718
+total: 12 memories
+
+[project-context | 2026-05-27] Active feature: honcho-memory Sprint 3
+[project-context | 2026-05-26] PLAN_honcho-inference seed for v2
+[explicit | 2026-05-12] Prefer immutable records for DTOs in Java
+...
+```
+
+### `/honcho forget <id>`
+
+Soft-delete via `PUT`, not `DELETE`. The record stays in the database but is excluded from all future searches and listings.
+
+```text
+$ /honcho forget msg_01HXY7K9AB
+soft-deleted: msg_01HXY7K9AB
+method: PUT
+endpoint: /v3/workspaces/claude_code/sessions/.../messages/msg_01HXY7K9AB
+body: { "metadata": { "deleted": true } }
+```
+
+Calling `/honcho forget` without an ID returns exit code 1 with usage info.
+
+### `/honcho status`
+
+Shows connection state, count of memories in the current session, config version, and flags.
+
+```text
+$ /honcho status
+connection: OK
+endpoint: https://honcho.pazzne.cloud
+workspace: claude_code
+peer: elton
+session: a1b2c3d4e5f60718
+
+config version: 0.1.0
+enabled: true
+inferenceEnabled: false
+topN: 5
+timeoutMs: 450
+
+session memories: 12
+peer memories (sample): 47
+```
+
+When the server is offline, returns `connection: FAIL` with the reason (timeout, 5xx, DNS).
+
+### `/honcho setup`
+
+Interactive wizard. Verifies connection, reads legacy `memory/*.md` files, shows preview, asks for confirmation, backs up originals to `memory/backup-YYYYMMDD/`, migrates to Honcho and archives the original `.md` files. Idempotent — running it multiple times is safe.
+
+Dry-run (no writes):
+
+```bash
+bun run .claude/skills/honcho-memory/scripts/setup.js --dry-run
+```
+
+---
+
+## The `[HONCHO MEMORY]` block
+
+When relevant memories exist, the hook writes the block below to stdout. Claude Code consumes that stdout as a system prompt extension for the current turn.
+
+```
+[HONCHO MEMORY]
+type: explicit | project: my-project | 2026-05-26T10:00:00Z
+Prefer immutable records for DTOs in Java
+
+type: project-context | project: development-utility-kit | 2026-05-26T09:00:00Z
+Active feature: honcho-memory-skill Sprint 3
+[/HONCHO MEMORY]
+```
+
+Rules:
+
+- `[HONCHO MEMORY]` and `[/HONCHO MEMORY]` tags are always present (even with an empty list)
+- Limit: `topN` memories (default 5)
+- Limit: 2,000 characters total — overflow is trimmed
+- Ordering: by semantic search relevance (peer) + chronological descending (session)
+- Deduplicated by ID before merging
+
+---
+
+## Configuration
+
+Config file path:
+
+- Windows: `C:\Users\<user>\.honcho\config.json`
+- macOS/Linux: `~/.honcho/config.json`
+
+Full structure:
+
+```json
+{
+  "apiKey": "<bearer-token — never logged, never committed>",
+  "peerName": "elton",
+  "workspace": "claude_code",
+  "endpoint": {
+    "baseUrl": "https://honcho.pazzne.cloud"
+  },
+  "enabled": true,
+  "logging": false,
+  "inferenceEnabled": false,
+  "topN": 5,
+  "timeoutMs": 450
+}
+```
+
+Fields:
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | string | — | Bearer token for authenticating with the Honcho server. Never appears in stdout, stderr or logs. **Never commit.** |
+| `peerName` | string | — | Logical user identity in Honcho. `explicit` and `inferred` memories are visible to this peer cross-project |
+| `workspace` | string | `claude_code` | Server namespace — multi-tenant separation |
+| `endpoint.baseUrl` | string | — | Honcho v3 server base URL |
+| `enabled` | boolean | `true` | If `false`, the hook returns immediately without calling the server |
+| `logging` | boolean | `false` | Stub for future verbose logging |
+| `inferenceEnabled` | boolean | `false` | Stub — when `true`, `on-stop.js` only writes `HONCHO_INFO: inference deferred to v2 PLAN, see PLAN_honcho-inference.md` to stderr |
+| `topN` | number | `5` | Cap on memories included in the block |
+| `timeoutMs` | number | `450` | Global hook operation timeout. Above this, returns exit 0 with no block |
+
+### Env var overrides
+
+Environment variables take precedence over `config.json` — useful for testing and CI.
+
+| Env var | Effect |
+|---|---|
+| `HONCHO_DRY_RUN=1` | Skip real Honcho calls; emit telemetry JSON to stdout for diagnostics |
+| `HONCHO_BASE_URL` | Override `endpoint.baseUrl` |
+| `HONCHO_TIMEOUT_MS` | Override `timeoutMs` in ms |
+| `HONCHO_INFERENCE_ENABLED=true` | Enable the inference stub in `on-stop.js` (writes `HONCHO_INFO`) |
+
+---
+
+## Initial setup
+
+Run the interactive wizard:
+
+```bash
+bun run .claude/skills/honcho-memory/scripts/setup.js
+```
+
+Steps:
+
+1. Verifies connectivity to the Honcho server
+2. Reads legacy `memory/*.md` files, if present
+3. Displays a preview/diff of what will be migrated
+4. Asks for explicit confirmation
+5. Backs up originals to `memory/backup-YYYYMMDD/`
+6. Migrates each `.md` file as an `explicit` message in Honcho
+7. Archives the original `.md` files
+
+Idempotent — running it more than once does not duplicate. If the server is offline, the wizard aborts with a clear message without touching files.
+
+Dry-run for diagnostics:
+
+```bash
+bun run .claude/skills/honcho-memory/scripts/setup.js --dry-run
+```
+
+---
+
+## Self-hosting Honcho v3
+
+Honcho v3 is an open-source semantic memory server. The harness does not include the server — it expects it to be reachable at an endpoint (cloud, your own VPS, local container). Consult the official Honcho project documentation for Docker Compose, PostgreSQL/pgvector schema, and auth setup.
+
+Endpoints used (verified in v3.0.6):
+
+| Operation | Method | Path |
+|---|---|---|
+| Create/get session | POST/GET | `/v3/workspaces/{ws}/sessions` |
+| Save memory (batch) | POST | `/v3/workspaces/{ws}/sessions/{session}/messages` |
+| Soft-delete | PUT | `/v3/workspaces/{ws}/sessions/{session}/messages/{id}` |
+| Peer-scoped search | POST | `/v3/workspaces/{ws}/peers/{peer}/search` |
+| List session messages | POST | `/v3/workspaces/{ws}/sessions/{session}/messages/list` |
+| Delete session (nuke) | DELETE | `/v3/workspaces/{ws}/sessions/{session}` |
+| OpenAPI spec | GET | `/openapi.json` (root, not `/v3/openapi.json`) |
+
+Full catalog in `.claude/skills/honcho-memory/docs/api-endpoints-verified.md`.
+
+---
+
+## Failure behavior (graceful degradation)
+
+Scenarios and responses:
+
+| Scenario | Hook response |
+|---|---|
+| Honcho offline (DNS, connection refused) | `HONCHO_WARN: <reason>` on stderr, empty stdout, exit 0 |
+| HTTP 5xx | `HONCHO_WARN: 5xx <body>` on stderr, empty stdout, exit 0 |
+| Timeout (default 450ms) | `HONCHO_WARN: timeout after 450ms` on stderr, empty stdout, exit 0 |
+| Missing config | `HONCHO_WARN: config not found` on stderr, empty stdout, exit 0 |
+| `enabled: false` in config | No warning, empty stdout, exit 0 |
+| Invalid API key (401) | `HONCHO_WARN: 401 unauthorized` on stderr, empty stdout, exit 0 |
+
+In **every** case Claude Code proceeds normally — no `[HONCHO MEMORY]` block, but no flow disruption.
+
+Diagnostic telemetry (in `HONCHO_DRY_RUN=1` mode or when future logging is enabled): stdout JSON with `{ peerSearchExecuted, sessionListExecuted, savedExplicit, timedOut, elapsedMs }`.
+
+---
+
+## Best practices
+
+### Use "remember that" for stack preferences
+
+Style preferences, architectural patterns and stack decisions are perfect candidates. They apply cross-project and rarely change.
+
+```text
+remember that I prefer immutable records for DTOs in Java
+remember that I always use Testcontainers, never H2 in integration tests
+remember that I want OnPush change detection on every Angular component
+```
+
+### Do NOT use Honcho for secrets
+
+Tokens, passwords, API keys, personal data should never go to Honcho. The Honcho `apiKey` itself is already on disk in `config.json` — do not pipe further secrets through the `[HONCHO MEMORY]` block.
+
+### Run `/honcho list` periodically
+
+Audit what is saved. Old, contradictory or wrong memories can influence responses. Clean up with `/honcho forget`.
+
+### Project-specific memories -> `project-context`
+
+Cross-project preferences: `explicit`. Current feature/sprint state: `project-context` (the `Stop` hook handles that automatically; no need to save manually).
+
+### Do not lean on inference (yet)
+
+`inferenceEnabled` is a stub in v1. Keep it `false`. v2 (`PLAN_honcho-inference.md`) will bring LLM-based inference — until then, explicit saves are the reliable path.
+
+---
+
+## Troubleshooting
+
+### `/honcho status` returns FAIL
+
+1. Check that `~/.honcho/config.json` exists and contains valid JSON
+2. Check `endpoint.baseUrl` — `curl -I <url>/openapi.json` should return 200
+3. Validate `apiKey` — a wrong key returns `connection: FAIL — 401 unauthorized`
+4. Is the Honcho server running? Container up, port exposed, no firewall
+
+### `[HONCHO MEMORY]` block does not appear in the prompt
+
+1. Hook registered? Check `~/.claude/settings.json` for a `UserPromptSubmit` entry pointing to `on-prompt-submit.js`
+2. Is `bun` on PATH? The hook uses `bun run`
+3. Restart the Claude Code session — hooks are loaded at startup
+4. `enabled: false` or missing `apiKey` in config forces empty stdout even with the hook active
+5. Run `HONCHO_DRY_RUN=1` manually and inspect the telemetry JSON
+
+### Old memories keep reappearing
+
+1. Verify they are indeed saved as `inferred` — that type would only be produced by v2, so it should not exist in v1
+2. Use `/honcho list` + `/honcho forget <id>` to clean them out
+3. If `inferenceEnabled` is `true`, switch it to `false` — it does not run inference, but the flag may be consumed by future routines
+
+### Slow hook, sluggish prompt
+
+1. `timeoutMs` too high. Default is 450ms; values > 1000ms are overkill. Lower it
+2. Network latency to the Honcho server? Consider hosting closer
+3. `topN` too high and the search payload slow? Lower to 3-5
+
+### Setup wizard hangs
+
+1. Run `--dry-run` first to validate read without write
+2. Check permissions on `memory/` — the wizard must create `memory/backup-YYYYMMDD/`
+3. If it hangs during migration, it is most likely server latency — interrupt, validate with `/honcho status`, re-run
+
+---
+
+## Cross-references
+
+- [Hooks reference](hooks-reference) — details on the `UserPromptSubmit` and `Stop` events that fire the honcho-memory scripts
+- [Architecture overview](architecture-overview) — where memory plugs into the broader pipeline
+- `.claude/skills/honcho-memory/SKILL.md` — canonical skill source
+- `.claude/skills/honcho-memory/docs/api-endpoints-verified.md` — full Honcho v3 endpoint catalog
+- `PLAN_honcho-inference.md` — future plan for LLM-based inference (v2)