@eltonssouza/development-utility-kit 0.10.1 → 0.12.0

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

@@ -1,394 +0,0 @@
-# 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)