pi-honcho-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 acsezen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# pi-honcho-memory
+
+Honcho-backed persistent memory extension for the [PI coding agent](https://github.com/nicholasgasior/pi-coding-agent). Full feature parity with the [Hermes agent Honcho plugin](https://github.com/NousResearch/hermes-agent).
+
+## Install
+
+```bash
+pi install npm:pi-honcho-memory
+# or from git
+pi install https://github.com/acsezen/pi-memory-honcho
+```
+
+## Setup
+
+1. Get a Honcho API key from [honcho.dev](https://honcho.dev) or self-host.
+2. Run `/honcho:setup` inside PI to configure your key, workspace, and peer names.
+3. Verify with `/honcho:doctor`.
+
+Or create `~/.honcho/config.json` manually:
+
+```json
+{
+  "apiKey": "hch-v3-...",
+  "peerName": "yourname",
+  "hosts": {
+    "pi": {
+      "workspace": "pi",
+      "aiPeer": "pi",
+      "recallMode": "hybrid"
+    }
+  }
+}
+```
+
+## Features
+
+### Memory tools
+
+| Tool | Description |
+|------|-------------|
+| `honcho_profile` | Retrieve what Honcho knows about the user |
+| `honcho_search` | Search durable memory for prior conversations and facts |
+| `honcho_context` | Synthesize memory context via dialectic reasoning |
+| `honcho_conclude` | Store a durable preference, fact, or decision |
+| `honcho_seed_identity` | Seed the AI peer's identity representation |
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/honcho:setup` | Interactive first-time configuration |
+| `/honcho:status` | Show connection, cache, and config status |
+| `/honcho:config` | Show effective config (redacted API key) |
+| `/honcho:doctor` | Preflight check for config, connectivity, session |
+| `/honcho:interview` | Save a preference or working style insight |
+| `/honcho:mode` | Switch recall mode (hybrid / context / tools) |
+| `/honcho:sync` | Force context refresh and flush pending uploads |
+| `/honcho:map` | Map current directory to a custom session name |
+
+### Lifecycle
+
+- **Session start**: Bootstraps Honcho connection, fetches context, migrates legacy memory files (MEMORY.md, USER.md, SOUL.md)
+- **Before agent start**: Injects persistent memory into the system prompt (user profile, peer cards, AI profile, project summary)
+- **Agent end**: Uploads conversation messages to Honcho
+- **Session shutdown/switch/fork/compact**: Flushes pending uploads
+
+## Configuration
+
+All fields can be set via `~/.honcho/config.json` (under `hosts.pi`) or environment variables.
+
+| Field | Env var | Default | Description |
+|-------|---------|---------|-------------|
+| `recallMode` | `HONCHO_RECALL_MODE` | `hybrid` | `hybrid` / `context` / `tools` |
+| `sessionStrategy` | `HONCHO_SESSION_STRATEGY` | `per-directory` | `per-directory` / `git-branch` / `pi-session` / `per-repo` / `global` |
+| `writeFrequency` | `HONCHO_WRITE_FREQUENCY` | `async` | `async` / `turn` / `session` / N (number) |
+| `injectionFrequency` | `HONCHO_INJECTION_FREQUENCY` | `every-turn` | `every-turn` / `first-turn` |
+| `saveMessages` | `HONCHO_SAVE_MESSAGES` | `true` | Upload conversation messages to Honcho |
+| `dialecticDynamic` | `HONCHO_DIALECTIC_DYNAMIC` | `true` | Auto-bump reasoning level by query length |
+| `dialecticMaxChars` | `HONCHO_DIALECTIC_MAX_CHARS` | `600` | Truncate dialectic results |
+| `dialecticMaxInputChars` | `HONCHO_DIALECTIC_MAX_INPUT_CHARS` | `10000` | Truncate dialectic queries |
+| `reasoningLevel` | `HONCHO_REASONING_LEVEL` | `low` | Base reasoning level for dialectic |
+| `reasoningLevelCap` | `HONCHO_REASONING_LEVEL_CAP` | none | Hard cap on reasoning level |
+| `contextTokens` | `HONCHO_CONTEXT_TOKENS` | `1200` | Token budget for injected context |
+| `contextRefreshTtlSeconds` | `HONCHO_CONTEXT_REFRESH_TTL_SECONDS` | `300` | TTL before re-fetching context |
+| `maxMessageLength` | `HONCHO_MAX_MESSAGE_LENGTH` | `25000` | Max chars per message chunk |
+| `searchLimit` | `HONCHO_SEARCH_LIMIT` | `8` | Max search results |
+| `sessionPeerPrefix` | `HONCHO_SESSION_PEER_PREFIX` | `false` | Prefix session keys with peer name |
+| `observationMode` | `HONCHO_OBSERVATION_MODE` | `directional` | `directional` / `unified` |
+| `contextCadence` | `HONCHO_CONTEXT_CADENCE` | `1` | Min turns between context API calls |
+| `dialecticCadence` | `HONCHO_DIALECTIC_CADENCE` | `1` | Min turns between dialectic calls |
+| `environment` | `HONCHO_ENVIRONMENT` | `production` | `local` / `production` |
+| `logging` | `HONCHO_LOGGING` | `true` | Enable console logging |
+
+### Manual session mappings
+
+Add `sessions` to your `~/.honcho/config.json` to map directories to specific session names:
+
+```json
+{
+  "sessions": {
+    "/home/user/project-a": "my-project-a",
+    "/home/user/project-b": "my-project-b"
+  }
+}
+```
+
+### Linked hosts
+
+Share memory across hosts (e.g., Claude Code, Codex, Hermes):
+
+```json
+{
+  "hosts": {
+    "pi": {
+      "linkedHosts": ["claude_code", "codex", "hermes"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/acsezen/pi-memory-honcho.git
+cd pi-memory-honcho
+npm install
+npm run typecheck
+npm test
+```
+
+## License
+
+MIT

package/extensions/client.ts

@@ -0,0 +1,64 @@
+import { Honcho } from "@honcho-ai/sdk";
+import type { Peer, Session } from "@honcho-ai/sdk";
+import type { HonchoConfig } from "./config.js";
+import { deriveSessionKey } from "./session.js";
+
+export interface HonchoHandles {
+  honcho: Honcho;
+  userPeer: Peer;
+  aiPeer: Peer;
+  session: Session | null;
+  sessionKey: string;
+  config: HonchoConfig;
+}
+
+let cachedHandles: HonchoHandles | null = null;
+let sessionPromise: Promise<Session> | null = null;
+
+export const getHandles = (): HonchoHandles | null => cachedHandles;
+export const clearHandles = (): void => {
+  cachedHandles = null;
+  sessionPromise = null;
+};
+
+const initSession = async (handles: HonchoHandles): Promise<Session> => {
+  const session = await handles.honcho.session(handles.sessionKey);
+  await session.addPeers([
+    [handles.userPeer, { observeMe: handles.config.observeMe, observeOthers: handles.config.observeOthers }],
+    [handles.aiPeer, { observeMe: handles.config.aiObserveMe, observeOthers: handles.config.aiObserveOthers }],
+  ]);
+  handles.session = session;
+  return session;
+};
+
+export const ensureSession = async (handles: HonchoHandles): Promise<Session> => {
+  if (handles.session) return handles.session;
+  if (sessionPromise) return sessionPromise;
+  sessionPromise = initSession(handles).finally(() => { sessionPromise = null; });
+  return sessionPromise;
+};
+
+export const bootstrap = async (config: HonchoConfig, cwd: string): Promise<HonchoHandles> => {
+  const honcho = new Honcho({
+    apiKey: config.apiKey,
+    baseURL: config.baseURL,
+    workspaceId: config.workspace,
+    environment: config.environment,
+  });
+  const sessionKey = await deriveSessionKey(cwd, config.sessionStrategy, config);
+  const [userPeer, aiPeer] = await Promise.all([
+    honcho.peer(config.peerName),
+    honcho.peer(config.aiPeer),
+  ]);
+
+  if (config.recallMode === "tools") {
+    // Lazy: defer session creation until first tool call
+    cachedHandles = { honcho, userPeer, aiPeer, session: null, sessionKey, config };
+    return cachedHandles;
+  }
+
+  // Eager: full init
+  cachedHandles = { honcho, userPeer, aiPeer, session: null, sessionKey, config };
+  await ensureSession(cachedHandles);
+  return cachedHandles;
+};

package/extensions/commands.ts

@@ -0,0 +1,198 @@
+import { Honcho } from "@honcho-ai/sdk";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { bootstrap, clearHandles, getHandles } from "./client.js";
+import { type RecallMode, normalizeRecallMode, resolveConfig, saveConfig, setRecallMode } from "./config.js";
+import { clearCachedContext, refreshCachedContext, renderCachedContext } from "./context.js";
+import { deriveSessionKey } from "./session.js";
+
+const parseCsv = (value: string | undefined, fallback: string[]): string[] => {
+  if (!value) return fallback;
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+};
+
+const statusText = async (): Promise<string> => {
+  const config = await resolveConfig();
+  const handles = getHandles();
+  const cache = renderCachedContext(config.contextTokens);
+  const sessionSource = handles?.sessionKey && config.sessions[process.cwd()]
+    ? "manual" : "derived";
+  return [
+    `Enabled: ${config.enabled ? "yes" : "no"}`,
+    `Connected: ${handles ? "yes" : "no"}`,
+    `Workspace: ${config.workspace}`,
+    `Peer: ${config.peerName}`,
+    `AI peer: ${config.aiPeer}`,
+    `Linked hosts: ${config.linkedHosts.length > 0 ? config.linkedHosts.join(", ") : "none"}`,
+    `Strategy: ${config.sessionStrategy}`,
+    `Recall mode: ${config.recallMode}`,
+    `Write frequency: ${config.writeFrequency}`,
+    `Injection: ${config.injectionFrequency}`,
+    `Dialectic dynamic: ${config.dialecticDynamic ? "on" : "off"}`,
+    `Reasoning level: ${config.reasoningLevel}${config.reasoningLevelCap ? ` (cap: ${config.reasoningLevelCap})` : ""}`,
+    `Context TTL: ${config.contextRefreshTtlSeconds}s`,
+    `Max message length: ${config.maxMessageLength}`,
+    `Save messages: ${config.saveMessages ? "yes" : "no"}`,
+    `Session key: ${handles?.sessionKey ?? "uninitialized"} (${sessionSource})`,
+    `Cache: ${cache ? `${cache.length} chars` : "empty"}`,
+  ].join("\n");
+};
+
+const connect = async (ctx: ExtensionContext): Promise<void> => {
+  clearHandles();
+  const config = await resolveConfig();
+  if (!config.enabled || !config.apiKey) throw new Error("Honcho is not configured.");
+  const handles = await bootstrap(config, ctx.cwd);
+  await refreshCachedContext(handles);
+};
+
+export const registerCommands = (pi: ExtensionAPI): void => {
+  pi.registerCommand("honcho:status", {
+    description: "Show Honcho connection and cache status",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(await statusText(), "info");
+    }
+  });
+
+  pi.registerCommand("honcho:setup", {
+    description: "Interactive first-time setup for Honcho in PI",
+    handler: async (_args, ctx) => {
+      const existing = await resolveConfig();
+      const maskedKey = existing.apiKey ? `${existing.apiKey.slice(0, 6)}...` : "hch-...";
+      const apiKeyInput = await ctx.ui.input("Honcho API key", maskedKey);
+      const apiKey = apiKeyInput === maskedKey ? existing.apiKey : apiKeyInput;
+      if (!apiKey) {
+        ctx.ui.notify("Setup cancelled: API key is required.", "warning");
+        return;
+      }
+      const peerName = await ctx.ui.input("Your peer name", existing.peerName);
+      const workspace = await ctx.ui.input("Honcho workspace", existing.workspace);
+      const aiPeer = await ctx.ui.input("AI peer name", existing.aiPeer);
+      const endpoint = await ctx.ui.input("Endpoint (optional)", existing.baseURL ?? "");
+      const linkedHosts = await ctx.ui.input(
+        "Linked hosts (comma-separated, optional)",
+        existing.linkedHosts.join(", "),
+      );
+      const strategyInput = await ctx.ui.input(
+        "Session strategy (per-directory / git-branch / pi-session)",
+        existing.sessionStrategy,
+      );
+      await saveConfig({
+        apiKey,
+        peerName: peerName ?? existing.peerName,
+        workspace: workspace ?? existing.workspace,
+        aiPeer: aiPeer ?? existing.aiPeer,
+        endpoint: endpoint || undefined,
+        linkedHosts: parseCsv(linkedHosts, existing.linkedHosts),
+        sessionStrategy:
+          strategyInput === "git-branch" || strategyInput === "pi-session" || strategyInput === "per-directory"
+            ? strategyInput
+            : existing.sessionStrategy,
+      });
+      await connect(ctx);
+      ctx.ui.notify("Honcho setup saved and connection initialized.", "info");
+    }
+  });
+
+  pi.registerCommand("honcho:config", {
+    description: "Show the current effective Honcho config for PI",
+    handler: async (_args, ctx) => {
+      const config = await resolveConfig();
+      const safe = { ...config, apiKey: config.apiKey ? `${config.apiKey.slice(0, 6)}...redacted` : undefined };
+      ctx.ui.notify(JSON.stringify(safe, null, 2), "info");
+    }
+  });
+
+  pi.registerCommand("honcho:interview", {
+    description: "Kick off a short preference interview and save a durable summary",
+    handler: async (_args, ctx) => {
+      const handles = getHandles();
+      if (!handles) {
+        ctx.ui.notify("Connect Honcho first with /honcho:setup.", "warning");
+        return;
+      }
+      const preference = await ctx.ui.input("What should PI remember about how you like to work?");
+      if (!preference) {
+        ctx.ui.notify("Interview cancelled.", "warning");
+        return;
+      }
+      await handles.aiPeer.conclusionsOf(handles.userPeer).create({
+        content: `User preference: ${preference}`,
+        sessionId: handles.session ?? undefined,
+      });
+      ctx.ui.notify("Saved interview insight to Honcho.", "info");
+    }
+  });
+
+  pi.registerCommand("honcho:doctor", {
+    description: "Run a quick Honcho preflight for config, connectivity, and session mapping",
+    handler: async (_args, ctx) => {
+      const config = await resolveConfig();
+      const checks: string[] = [];
+
+      checks.push(`api_key: ${config.apiKey ? "ok" : "missing"}`);
+      checks.push(`workspace: ${config.workspace}`);
+      checks.push(`session_strategy: ${config.sessionStrategy}`);
+      checks.push(`linked_hosts: ${config.linkedHosts.length > 0 ? config.linkedHosts.join(", ") : "none"}`);
+
+      if (!config.enabled || !config.apiKey) {
+        ctx.ui.notify([...checks, "connectivity: skipped (Honcho not configured)"].join("\n"), "warning");
+        return;
+      }
+
+      try {
+        const honcho = new Honcho({ apiKey: config.apiKey, baseURL: config.baseURL, workspaceId: config.workspace, environment: config.environment });
+        const sessionKey = await deriveSessionKey(ctx.cwd, config.sessionStrategy, config);
+        await Promise.all([
+          honcho.peer(config.peerName),
+          honcho.peer(config.aiPeer),
+          honcho.session(sessionKey)
+        ]);
+        checks.push(`connectivity: ok`);
+        checks.push(`session_key: ${sessionKey}`);
+        ctx.ui.notify(checks.join("\n"), "info");
+      } catch (error) {
+        checks.push(`connectivity: failed`);
+        checks.push(`error: ${error instanceof Error ? error.message : String(error)}`);
+        ctx.ui.notify(checks.join("\n"), "error");
+      }
+    }
+  });
+
+  pi.registerCommand("honcho:mode", {
+    description: "Switch recall mode (hybrid / context / tools)",
+    handler: async (args, ctx) => {
+      const mode = normalizeRecallMode(args?.trim());
+      setRecallMode(mode);
+      ctx.ui.notify(`Recall mode set to: ${mode}`, "info");
+    },
+  });
+
+  pi.registerCommand("honcho:map", {
+    description: "Map the current directory to a custom Honcho session name",
+    handler: async (args, ctx) => {
+      const name = args?.trim();
+      if (!name) {
+        ctx.ui.notify("Usage: /honcho:map <session-name>", "warning");
+        return;
+      }
+      ctx.ui.notify(`Session mapping: ${ctx.cwd} → ${name}\nNote: add to ~/.honcho/config.json sessions manually for persistence.`, "info");
+    },
+  });
+
+  pi.registerCommand("honcho:sync", {
+    description: "Force context refresh and flush pending uploads",
+    handler: async (_args, ctx) => {
+      const handles = getHandles();
+      if (!handles) {
+        ctx.ui.notify("Connect Honcho first with /honcho:setup.", "warning");
+        return;
+      }
+      clearCachedContext();
+      await refreshCachedContext(handles);
+      ctx.ui.notify("Context refreshed.", "info");
+    },
+  });
+};