@eltonssouza/development-utility-kit 1.0.0

package/.claude/skills/honcho-memory/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: honcho-memory
+description: |
+  Persistent cross-session memory for Claude Code via Honcho v3 self-hosted.
+  Triggers on: "honcho memory", "memória honcho", "honcho skill",
+  "lembra que", "remember that", "memoriza", "memorize this",
+  "never do", "always do", "never use", "always use",
+  "/honcho save", "/honcho search", "/honcho list",
+  "/honcho forget", "/honcho status", "/honcho setup",
+  "save memory", "search memory", "list memories",
+  "forget memory", "honcho status", "honcho setup",
+  "memória persistente", "persistent memory", "cross-session memory".
+---
+
+# honcho-memory
+
+Persistent cross-session memory for Claude Code backed by **Honcho v3 self-hosted**.
+
+Memories survive between sessions. Relevant memories are injected automatically
+into every prompt via the `[HONCHO MEMORY]` block before Claude Code processes them.
+
+---
+
+## Overview
+
+The skill integrates Honcho v3 as a semantic memory backend. On every `UserPromptSubmit`
+hook, the skill:
+
+1. Detects explicit memory triggers ("lembra que", "remember that", "memoriza", "never ...", "always ...").
+2. Saves any explicit memory **before** any search (BR-001).
+3. Executes hybrid search in `Promise.all`:
+   - **Peer-scoped** (`POST /v3/workspaces/{ws}/peers/{peer}/search`) — retrieves `explicit`
+     and `inferred` memories, cross-project preferences.
+   - **Session-scoped** (`POST /v3/workspaces/{ws}/sessions/{sessionId}/messages/list`) — retrieves
+     `project-context` memories for the current directory.
+4. Merges results by relevance, caps at `topN` items and 2,000 characters.
+5. Injects the `[HONCHO MEMORY]...[/HONCHO MEMORY]` block into stdout (system prompt extension).
+
+On `Stop`, the hook saves the active feature/sprint context as `project-context`.
+
+---
+
+## Subcommands
+
+All subcommands are available via the CLI:
+
+```
+bun run .claude/skills/honcho-memory/scripts/cli.js <subcommand> [args]
+```
+
+| Subcommand | Description |
+|---|---|
+| `/honcho save <text>` | Save an explicit memory. Prints the saved message ID. |
+| `/honcho search <query>` | Semantic search — returns top-N relevant memories (excludes soft-deleted). |
+| `/honcho list` | List all memories in the current session (excludes soft-deleted). |
+| `/honcho forget <id>` | Soft-delete a memory via `PUT /v3/workspaces/{ws}/sessions/{sessionId}/messages/{id}` with `{ "metadata": { "deleted": true } }`. Note: uses PUT, NOT DELETE — this is a soft-delete. Calling `forget` without an ID returns exit code 1. |
+| `/honcho status` | Show connection status (OK/FAIL), memory count, config version, `enabled`, `inferenceEnabled` flags. |
+| `/honcho setup` | Interactive wizard: verifies connection, migrates `memory/*.md` to Honcho with backup. |
+
+### forget — soft-delete via PUT
+
+`forget <id>` never calls HTTP DELETE. It calls:
+
+```
+PUT /v3/workspaces/{ws}/sessions/{sessionId}/messages/{id}
+Body: { "metadata": { "deleted": true } }
+```
+
+This is a **soft-delete** — the record is preserved in the database but excluded from
+all future list/search results. The CLI stdout contains `"method": "PUT"` to confirm.
+
+---
+
+## Automatic triggers
+
+The following patterns in a user prompt trigger **immediate explicit save** before any search:
+
+| Pattern | Example |
+|---|---|
+| `lembra que` | "lembra que prefiro records imutáveis em DTOs Java" |
+| `remember that` | "remember that I prefer immutable records" |
+| `memoriza` | "memoriza: usar OnPush em todos os componentes Angular" |
+| `never ...` | "never use var in TypeScript" |
+| `always ...` | "always add JSDoc to public methods" |
+
+---
+
+## [HONCHO MEMORY] block
+
+When memories are available, the following block is injected into the system prompt extension:
+
+```
+[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]
+```
+
+The block is limited to `topN` memories (default: 5) and 2,000 characters total.
+Both opening and closing tags (`[HONCHO MEMORY]` / `[/HONCHO MEMORY]`) are always present.
+
+---
+
+## Graceful degradation
+
+When Honcho is unavailable (network timeout, 5xx, DNS failure):
+
+- The hook aborts after `timeoutMs` ms (default: 450ms).
+- A `HONCHO_WARN: <reason>` message is written to **stderr**.
+- An **empty string** is written to stdout.
+- Exit code is **0** — Claude Code proceeds normally without memory.
+
+This ensures the skill **never blocks** the main workflow. Degradation is graceful.
+
+---
+
+## Configuration
+
+Config file: `C:\Users\elton\.honcho\config.json`
+
+```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
+}
+```
+
+**Security**: `apiKey` is never printed to stdout, stderr, or any log. It is never committed to git.
+
+### Session strategy
+
+Session ID = `sha256(CWD)[:16]` — one bucket per project directory, never rotated.
+All memories for a given directory accumulate in the same session indefinitely.
+
+---
+
+## Setup
+
+Run the interactive wizard:
+
+```bash
+bun run .claude/skills/honcho-memory/scripts/setup.js
+```
+
+Or dry-run (no writes):
+
+```bash
+bun run .claude/skills/honcho-memory/scripts/setup.js --dry-run
+```
+
+The wizard:
+1. Verifies the Honcho connection.
+2. Reads existing `memory/*.md` files (legacy memories).
+3. Shows a preview/diff.
+4. Asks for confirmation.
+5. Backs up originals to `memory/backup-YYYYMMDD/`.
+6. Migrates memories to Honcho.
+7. Archives the original `.md` files.
+
+Setup is **idempotent** — running it multiple times is safe.
+
+---
+
+## Hooks registration
+
+Hooks are registered in `C:\Users\elton\.claude\settings.json` (global scope):
+
+- **UserPromptSubmit** → `bun run C:/development/tools/development-utility-kit/.claude/skills/honcho-memory/hooks/on-prompt-submit.js`
+- **Stop** → `bun run C:/development/tools/development-utility-kit/.claude/skills/honcho-memory/hooks/on-stop.js`
+
+Path uses forward slashes (IR-006 — accepted by the Claude Code hook runner on Windows).
+Implementation lives in the harness at `C:/development/tools/development-utility-kit/.claude/skills/honcho-memory/` (Option B per D-003).
+
+---
+
+## Inference (deferred)
+
+`inferenceEnabled: true` in config is a **stub** for `PLAN_honcho-inference.md`.
+When enabled, `on-stop.js` emits `HONCHO_INFO: inference deferred to v2 PLAN, see PLAN_honcho-inference.md` in stderr and proceeds without LLM inference calls.
+
+---
+
+## API endpoints (verified — Honcho v3.0.6)
+
+| Operation | Method | Path |
+|---|---|---|
+| Get/create session | POST/GET | `/v3/workspaces/{ws}/sessions` |
+| Save memory (batch) | POST | `/v3/workspaces/{ws}/sessions/{session}/messages` |
+| Soft-delete memory | 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`) |
+
+See `.claude/skills/honcho-memory/docs/api-endpoints-verified.md` for full details.

package/.claude/skills/honcho-memory/docs/api-endpoints-verified.md

@@ -0,0 +1,75 @@
+# Honcho v3 API Endpoints — Verified
+
+> verifiedAt: 2026-05-26T19:05:19Z
+> Source: GET https://honcho.pazzne.cloud/openapi.json (note: spec served at root, not /v3/openapi.json)
+> API version: 3.0.6 (openapi: 3.1.0)
+
+## Summary of Deviations from DISCOVERY
+
+The DISCOVERY document described a `workspaces/{ws}/apps/{app}/users/{user}/...` hierarchy.
+The actual v3 API uses `workspaces/{ws}/sessions/{session}/...` with `peers/{peer}` instead of users/apps.
+There is **no individual message DELETE** endpoint — `deleteMemory` is implemented by deleting the containing session.
+
+## Verified Endpoints (6 operations mapped to client functions)
+
+| Client Function | Method | Actual Path | operationId | DISCOVERY Path | Status |
+|---|---|---|---|---|---|
+| `getOrCreateApp` | `POST` | `/v3/workspaces` | `get_or_create_workspace_v3_workspaces_post` | `/v3/workspaces/{ws}/apps` | `differs: no apps concept — workspace IS the app` |
+| `getOrCreateSession` | `POST` | `/v3/workspaces/{workspace_id}/sessions` | `get_or_create_session_v3_workspaces__workspace_id__sessions_post` | `/v3/workspaces/{ws}/apps/{app}/users/{user}/sessions` | `differs: no user/app nesting` |
+| `saveMemory` | `POST` | `/v3/workspaces/{workspace_id}/sessions/{session_id}/messages` | `create_messages_for_session_v3_workspaces__workspace_id__sessions__session_id__messages_post` | `/v3/workspaces/{ws}/apps/{app}/users/{user}/sessions/{session}/messages` | `differs: shorter path, batch body` |
+| `searchMemories` | `POST` | `/v3/workspaces/{workspace_id}/peers/{peer_id}/search` | `search_peer_v3_workspaces__workspace_id__peers__peer_id__search_post` | `/v3/workspaces/{ws}/apps/{app}/users/{user}/search` | `differs: peer-scoped, not user-scoped` |
+| `listMemories` | `POST` | `/v3/workspaces/{workspace_id}/sessions/{session_id}/messages/list` | `get_messages_v3_workspaces__workspace_id__sessions__session_id__messages_list_post` | `/v3/workspaces/{ws}/apps/{app}/users/{user}/sessions/{session}/messages` | `differs: POST + /list suffix` |
+| `deleteMemory` | `DELETE` | `/v3/workspaces/{workspace_id}/sessions/{session_id}` | `delete_session_v3_workspaces__workspace_id__sessions__session_id__delete` | `DELETE /v3/workspaces/{ws}/apps/{app}/users/{user}/sessions/{session}/messages/{id}` | `differs: no individual message delete; deletes whole session` |
+
+## Additional Useful Endpoints
+
+| Method | Path | Summary |
+|---|---|---|
+| `GET` | `/health` | Health check (no auth required) |
+| `POST` | `/v3/workspaces/{workspace_id}/search` | Search across entire workspace |
+| `POST` | `/v3/workspaces/{workspace_id}/sessions/{session_id}/search` | Search within session |
+| `DELETE` | `/v3/workspaces/{workspace_id}` | Delete workspace |
+| `PUT` | `/v3/workspaces/{workspace_id}/sessions/{session_id}/messages/{message_id}` | Update message metadata |
+
+## Key Schema Differences
+
+### WorkspaceCreate (POST /v3/workspaces)
+```json
+{ "id": "string (required, pattern: ^[a-zA-Z0-9_-]+$)", "metadata": "object" }
+```
+Response: workspace object with same `id`.
+
+### SessionCreate (POST /v3/workspaces/{workspace_id}/sessions)
+```json
+{ "id": "string (required)", "metadata": "object|null", "peers": "object|null" }
+```
+Response: session object.
+
+### MessageBatchCreate (POST .../messages)
+```json
+{
+  "messages": [
+    { "content": "string (required)", "peer_id": "string (required)", "metadata": "object|null" }
+  ]
+}
+```
+**Note**: `peer_id` is required per message. Use `peerName` from config as the peer_id.
+
+### MessageSearchOptions (POST .../peers/{peer_id}/search)
+```json
+{ "query": "string (required)", "filters": "object|null", "limit": "integer (1-100, default 10)" }
+```
+
+### MessageGet (POST .../messages/list)
+```json
+{ "filters": "object|null" }
+```
+Response: `Page[Message]` with `{ items, total, page, size, pages }`.
+
+## Architecture Notes for honcho-client.js
+
+- **Workspace** = equivalent to "app" in DISCOVERY. Use fixed id from config (`hosts.claude_code.workspace`).
+- **Session** = per-directory session. ID derived from SHA-256(CWD)[:16].
+- **Peer** = the user identity. Use `peerName` from config (default: "elton").
+- **getOrCreateApp** in client = `POST /v3/workspaces` (idempotent by id).
+- **deleteMemory** in client = `DELETE /v3/workspaces/{ws}/sessions/{sessionId}` (entire session, not single message). For granular "forget", use `PUT .../messages/{id}` to update metadata with `deleted: true` marker.

package/.claude/skills/honcho-memory/hooks/on-prompt-submit.js

@@ -0,0 +1,221 @@
+/**
+ * on-prompt-submit.js — UserPromptSubmit hook
+ *
+ * Triggered by Claude Code before each user prompt is submitted.
+ * Reads the user's prompt from stdin, then:
+ * 1. Detects explicit memory triggers ("lembra que", "remember that", "memoriza", "never ", "always ")
+ *    → saves memory immediately with metadata.type = "explicit", metadata.source = "user"
+ * 2. Runs hybrid search in Promise.all (peer-scoped + session-scoped) within timeout budget
+ * 3. Injects [HONCHO MEMORY] block into stdout as system prompt extension
+ *
+ * Telemetry: stdout JSON contains peerSearchExecuted + sessionListExecuted fields.
+ *
+ * Env vars:
+ *   HONCHO_DRY_RUN=1      — skip real Honcho calls, emit telemetry JSON to stdout
+ *   HONCHO_BASE_URL       — override base URL (env takes precedence over config)
+ *   HONCHO_TIMEOUT_MS     — override timeout in ms
+ *
+ * Exit codes:
+ *   0 — always (NFR-002: never blocks Claude Code)
+ *
+ * References: FR-003a, FR-003b, FR-003c, BR-001, BR-008, NFR-001, NFR-002
+ */
+
+import { createHash } from "crypto";
+import { createClient, loadConfig } from "../lib/honcho-client.js";
+import { buildContextBlock } from "../lib/memory-injector.js";
+
+const DRY_RUN = process.env.HONCHO_DRY_RUN === "1";
+
+const CONFIG_PATH = "C:\\Users\\elton\\.honcho\\config.json";
+
+/** Read config, override with env vars where applicable. Returns null if disabled or missing. */
+function getEffectiveConfig() {
+  const cfg = loadConfig();
+
+  // If env vars specify base URL, build a synthetic config
+  if (process.env.HONCHO_BASE_URL) {
+    // Build minimal config from env — useful for testing with no config file
+    const base = {
+      apiKey: cfg?.apiKey ?? "dry-run-key",
+      peerName: cfg?.peerName ?? "elton",
+      workspace: cfg?.workspace ?? "claude_code",
+      endpoint: { baseUrl: process.env.HONCHO_BASE_URL },
+      enabled: true,
+      topN: cfg?.topN ?? 5,
+      timeoutMs: process.env.HONCHO_TIMEOUT_MS
+        ? parseInt(process.env.HONCHO_TIMEOUT_MS, 10)
+        : (cfg?.timeoutMs ?? 450),
+    };
+    return base;
+  }
+
+  if (!cfg) return null;
+  if (cfg.enabled === false) return null;
+
+  // Apply env override for timeout
+  if (process.env.HONCHO_TIMEOUT_MS) {
+    cfg.timeoutMs = parseInt(process.env.HONCHO_TIMEOUT_MS, 10);
+  }
+
+  return cfg;
+}
+
+/** Derive session ID from CWD: sha256(CWD)[:16] */
+function deriveSessionId(cwd) {
+  return createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+}
+
+/** Detect explicit memory trigger patterns (BR-001) */
+function detectExplicitTrigger(prompt) {
+  const lower = prompt.toLowerCase();
+  return (
+    lower.includes("lembra que") ||
+    lower.includes("remember that") ||
+    lower.includes("memoriza") ||
+    lower.startsWith("never ") ||
+    lower.includes("\nnever ") ||
+    lower.startsWith("always ") ||
+    lower.includes("\nalways ")
+  );
+}
+
+/** Write to stderr without logging apiKey */
+function warn(msg) {
+  process.stderr.write("HONCHO_WARN: " + msg + "\n");
+}
+
+async function main() {
+  // Read stdin (prompt text)
+  let prompt = "";
+  try {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    prompt = Buffer.concat(chunks).toString("utf8").trim();
+  } catch {
+    // stdin read failed — proceed with empty prompt
+  }
+
+  const cfg = getEffectiveConfig();
+  const cwd = process.cwd();
+  const sessionId = deriveSessionId(cwd);
+  const isExplicit = detectExplicitTrigger(prompt);
+
+  // DRY_RUN mode: simulate execution without real Honcho calls
+  if (DRY_RUN) {
+    const telemetry = {
+      dryRun: true,
+      peerSearchExecuted: true,
+      sessionListExecuted: true,
+      saved: isExplicit ? true : false,
+      sessionId,
+      prompt: prompt.slice(0, 100),
+    };
+    if (isExplicit) {
+      telemetry.savedType = "explicit";
+      telemetry.savedSource = "user";
+    }
+    process.stdout.write(JSON.stringify(telemetry) + "\n");
+    process.exit(0);
+  }
+
+  // No config or disabled — silent no-op
+  if (!cfg) {
+    process.exit(0);
+  }
+
+  const workspace = cfg.workspace ?? "claude_code";
+  const peerId = cfg.peerName ?? "elton";
+  const topN = cfg.topN ?? 5;
+  const timeoutMs = cfg.timeoutMs ?? 450;
+  const project = cwd.split(/[/\\]/).pop() ?? "unknown";
+
+  const client = createClient({
+    baseUrl: cfg.endpoint.baseUrl,
+    apiKey: cfg.apiKey,
+    timeoutMs,
+  });
+
+  // Step 1: Save explicit memory immediately (BR-001)
+  if (isExplicit) {
+    try {
+      await client.saveMemory(workspace, sessionId, peerId, prompt, {
+        type: "explicit",
+        source: "user",
+        project,
+        directory: cwd,
+        timestamp: new Date().toISOString(),
+      });
+    } catch {
+      // Never block — ignore save errors
+    }
+  }
+
+  // Step 2: Hybrid search within timeout budget (FR-003a + FR-003b, NFR-001)
+  let peerResults = null;
+  let sessionResults = null;
+  let peerSearchExecuted = false;
+  let sessionListExecuted = false;
+
+  try {
+    const [peerRes, sessionRes] = await Promise.all([
+      client.searchMemories(workspace, peerId, prompt || "general context", topN).then((r) => {
+        peerSearchExecuted = true;
+        return r;
+      }),
+      client.listMemories(workspace, sessionId, {}).then((r) => {
+        sessionListExecuted = true;
+        return r;
+      }),
+    ]);
+    peerResults = peerRes;
+    sessionResults = sessionRes;
+  } catch {
+    // Failure in Promise.all — warn and continue
+    warn("search failed, proceeding without memories");
+  }
+
+  // If both failed (null), emit warning
+  if (!peerResults && !sessionResults) {
+    warn("no memories retrieved — Honcho may be unreachable");
+    process.exit(0);
+  }
+
+  // Step 3: Merge results (FR-003c)
+  // peer-search returns scored items; session-list returns recency-ordered items
+  const peerItems = peerResults?.items ?? [];
+  const sessionItems = sessionResults?.items ?? [];
+
+  // Merge: peer items first (relevance-scored), then session items (recency proxy)
+  // Deduplicate by content (simple string match)
+  const seen = new Set();
+  const merged = [];
+  for (const item of [...peerItems, ...sessionItems]) {
+    const key = item.content?.trim();
+    if (key && !seen.has(key)) {
+      seen.add(key);
+      merged.push(item);
+    }
+  }
+
+  const topMemories = merged.slice(0, topN);
+
+  if (topMemories.length === 0) {
+    process.exit(0);
+  }
+
+  // Step 4: Build and inject context block
+  const contextBlock = buildContextBlock(topMemories);
+  if (contextBlock) {
+    process.stdout.write(contextBlock + "\n");
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  warn("unexpected error: " + (err?.message ?? String(err)));
+  process.exit(0);
+});

package/.claude/skills/honcho-memory/hooks/on-stop.js

@@ -0,0 +1,193 @@
+/**
+ * on-stop.js — Stop hook
+ *
+ * Triggered by Claude Code when a session ends.
+ * Extracts the active feature/sprint from CLAUDE.md and recent git log,
+ * then saves a memory with metadata.type = "project-context".
+ *
+ * If inferenceEnabled is true (config or HONCHO_INFERENCE_ENABLED=true env):
+ *   writes "HONCHO_INFO: inference deferred to v2 PLAN, see PLAN_honcho-inference.md" to stderr
+ *   and proceeds WITHOUT performing inference (NFR-007, BR-006).
+ *
+ * Env vars:
+ *   HONCHO_DRY_RUN=1             — skip real Honcho calls, print JSON to stdout
+ *   HONCHO_BASE_URL              — override base URL
+ *   HONCHO_TIMEOUT_MS            — override timeout in ms
+ *   HONCHO_INFERENCE_ENABLED     — "true" to enable inference stub (writes HONCHO_INFO)
+ *
+ * Exit codes:
+ *   0 — always (IR-004: non-blocking, fail-silent)
+ *
+ * References: FR-004, BR-006, NFR-007, IR-004
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import { createHash } from "crypto";
+import { createClient, loadConfig } from "../lib/honcho-client.js";
+
+const DRY_RUN = process.env.HONCHO_DRY_RUN === "1";
+const INFERENCE_ENABLED =
+  process.env.HONCHO_INFERENCE_ENABLED === "true";
+
+/** Write to stderr */
+function warn(msg) {
+  process.stderr.write("HONCHO_WARN: " + msg + "\n");
+}
+
+function info(msg) {
+  process.stderr.write("HONCHO_INFO: " + msg + "\n");
+}
+
+/** Derive session ID from CWD: sha256(CWD)[:16] */
+function deriveSessionId(cwd) {
+  return createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+}
+
+/**
+ * Extract active feature/sprint from CLAUDE.md in the given directory.
+ * Returns a short string or null.
+ */
+function extractFeatureFromClaudeMd(cwd) {
+  const claudeMdPath = join(cwd, "CLAUDE.md");
+  if (!existsSync(claudeMdPath)) return null;
+  try {
+    const content = readFileSync(claudeMdPath, "utf8");
+    // Look for sprint / feature / plan mentions
+    const sprintMatch = content.match(/(?:sprint|Sprint)\s+([\w-]+)/i);
+    const planMatch = content.match(/PLAN_(\w[\w-]*)/i);
+    const featureMatch = content.match(/feature\/([\w-]+)/i);
+    if (planMatch) return `PLAN_${planMatch[1]}`;
+    if (sprintMatch) return `Sprint ${sprintMatch[1]}`;
+    if (featureMatch) return `feature/${featureMatch[1]}`;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract recent git log summary (last 3 commits, one-line format).
+ * Returns a string or null.
+ */
+function extractRecentGitLog(cwd) {
+  try {
+    const log = execSync("git log --oneline -3", {
+      cwd,
+      timeout: 2000,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8",
+    });
+    return log.trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Get effective config, applying env overrides. */
+function getEffectiveConfig() {
+  const cfg = loadConfig();
+
+  if (process.env.HONCHO_BASE_URL) {
+    return {
+      apiKey: cfg?.apiKey ?? "dry-run-key",
+      peerName: cfg?.peerName ?? "elton",
+      workspace: cfg?.workspace ?? "claude_code",
+      endpoint: { baseUrl: process.env.HONCHO_BASE_URL },
+      enabled: true,
+      timeoutMs: process.env.HONCHO_TIMEOUT_MS
+        ? parseInt(process.env.HONCHO_TIMEOUT_MS, 10)
+        : (cfg?.timeoutMs ?? 450),
+      inferenceEnabled: INFERENCE_ENABLED || (cfg?.inferenceEnabled ?? false),
+    };
+  }
+
+  if (!cfg) return null;
+
+  if (process.env.HONCHO_TIMEOUT_MS) {
+    cfg.timeoutMs = parseInt(process.env.HONCHO_TIMEOUT_MS, 10);
+  }
+
+  // env var overrides config flag
+  cfg.inferenceEnabled = INFERENCE_ENABLED || (cfg.inferenceEnabled ?? false);
+
+  return cfg;
+}
+
+async function main() {
+  const cwd = process.cwd();
+  const sessionId = deriveSessionId(cwd);
+  const project = cwd.split(/[/\\]/).pop() ?? "unknown";
+
+  // Extract context from CLAUDE.md and git log
+  const featureInfo = extractFeatureFromClaudeMd(cwd);
+  const gitLog = extractRecentGitLog(cwd);
+
+  const contextParts = [];
+  if (featureInfo) contextParts.push(`Active: ${featureInfo}`);
+  if (gitLog) contextParts.push(`Recent commits:\n${gitLog}`);
+  contextParts.push(`Directory: ${cwd}`);
+  contextParts.push(`Project: ${project}`);
+
+  const content = contextParts.join("\n");
+
+  const memoryPayload = {
+    type: "project-context",
+    project,
+    directory: cwd,
+    timestamp: new Date().toISOString(),
+    source: "user",
+    sessionId,
+    featureInfo: featureInfo ?? null,
+  };
+
+  // Check inference flag (BR-006, NFR-007) — always before any Honcho call
+  const cfg = getEffectiveConfig();
+  const inferenceEnabled = cfg?.inferenceEnabled || INFERENCE_ENABLED;
+
+  if (inferenceEnabled) {
+    info("inference deferred to v2 PLAN, see PLAN_honcho-inference.md");
+    // No LLM call — proceed with project-context save only
+  }
+
+  // DRY_RUN mode
+  if (DRY_RUN) {
+    const output = {
+      dryRun: true,
+      ...memoryPayload,
+    };
+    process.stdout.write(JSON.stringify(output) + "\n");
+    process.exit(0);
+  }
+
+  // No config or disabled — silent no-op
+  if (!cfg || cfg.enabled === false) {
+    process.exit(0);
+  }
+
+  const workspace = cfg.workspace ?? "claude_code";
+  const peerId = cfg.peerName ?? "elton";
+  const timeoutMs = Math.min(cfg.timeoutMs ?? 450, 2000); // cap at 2s for stop hook
+
+  const client = createClient({
+    baseUrl: cfg.endpoint.baseUrl,
+    apiKey: cfg.apiKey,
+    timeoutMs,
+  });
+
+  // Save project-context memory
+  try {
+    await client.saveMemory(workspace, sessionId, peerId, content, memoryPayload);
+  } catch {
+    // Non-blocking — ignore errors
+    warn("failed to save project-context memory");
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  warn("unexpected error in on-stop: " + (err?.message ?? String(err)));
+  process.exit(0);
+});