pi-cmem 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Copyright (c) 2026 ezoushen
+
+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.

package/README.md

@@ -0,0 +1,86 @@
+# pi-cmem
+
+Connect Pi to a shared claude-mem worker through its HTTP API. The package registers
+one `memory_recall` tool, optionally captures Pi observations, and can inject a memory
+digest before each turn.
+
+claude-mem is licensed under Apache-2.0. `pi-cmem` is an independent MIT-licensed HTTP
+client; it does not import claude-mem code.
+
+`@husniadil/pi-mem` is the fuller alternative: it can spawn the worker and offers a
+three-tool recall workflow. This package deliberately stays smaller. In particular,
+it does not prefix project names with `pi-`, so Pi, Claude Code, and Codex share one
+repository namespace while `platformSource` still distinguishes the producing agent.
+
+## External contract
+
+A claude-mem worker must expose its health, search, context-injection, session, and
+observation HTTP endpoints at the configured host and port. The default is the
+worker's local endpoint at `127.0.0.1:37777`.
+
+The optional fallback is a Python helper script that can search the same Chroma data
+when the worker is unavailable. Capture and context injection always require the
+worker; the fallback supports recall only.
+
+## If the contract is unmet
+
+At session start, an unreachable worker produces one warning without preventing Pi
+from loading. Capture and context injection are disabled for that outage. Recall uses
+the configured fallback helper when it exists; otherwise `memory_recall` reports that
+recall is unavailable. A reachable worker returning no matches produces “No matching
+memories found.”
+
+In pi's print (`-p`) and json modes there is no UI to notify, so warnings that would
+otherwise be silent there are written to stderr instead, once per distinct reason per
+process.
+
+`/memory-status` reports worker reachability, project scope, session identity, and the
+capture/injection state.
+
+## Settings
+
+Settings resolve from `pi-cmem.json` in the global Pi config directory, then from a
+trusted project's Pi config directory, then from the environment. Later sources win.
+Project settings are ignored when the project is untrusted.
+
+`workerHost` and `workerPort` add one more layer below those: when neither an explicit
+setting nor the environment names them, they are discovered from claude-mem's own
+published settings (`~/.claude-mem/settings.json`, or
+`$CLAUDE_MEM_DATA_DIR/settings.json`), which is where the worker it started actually
+listens. claude-mem writes the port as a JSON string; discovery accepts both a string
+and a number. Full precedence for these two keys: documented default -> claude-mem's
+published settings -> global `pi-cmem.json` -> trusted project `pi-cmem.json` ->
+environment. An unreachable-worker warning names which of `host`/`port` came from
+discovery.
+
+| JSON key | Default | Environment override | Meaning |
+|---|---|---|---|
+| `disabled` | `false` | `PI_CMEM_DISABLED=1` | Disable bridge activity. |
+| `capture` | `true` | `PI_CMEM_CAPTURE=0` | Write prompts, tool observations, and summaries through the worker. |
+| `inject` | `false` | `PI_CMEM_INJECT=1` | Inject a worker-produced context digest before each turn. |
+| `workerHost` | `"127.0.0.1"` | `PI_CMEM_WORKER_HOST` | claude-mem worker host; discovered from claude-mem's own settings when not set explicitly. |
+| `workerPort` | `37777` | `PI_CMEM_WORKER_PORT` | claude-mem worker port; discovered from claude-mem's own settings when not set explicitly. |
+| `project` | `""` | `PI_CMEM_PROJECT` | Project override; empty uses the current working-directory basename. |
+| `fallbackPath` | `""` | `PI_CMEM_FALLBACK_PATH` | Optional Chroma search helper; empty means no fallback. |
+
+Example:
+
+```json
+{
+  "capture": true,
+  "inject": false,
+  "project": "shared-repository"
+}
+```
+
+## Install and verify
+
+```sh
+pi install npm:pi-cmem
+```
+
+Start a session and run `/memory-status`. With a reachable worker, call
+`memory_recall` with a known query and confirm the result belongs to the current bare
+repository namespace. With the worker stopped, confirm that startup warns once and
+that recall either uses the configured helper or reports the missing fallback. This
+check exercises the external contract without depending on any particular deployment.

package/cmem.js

@@ -0,0 +1,394 @@
+// extensions/cmem/cmem.ts
+import { Type } from "typebox";
+import { execFile } from "node:child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join as join2 } from "node:path";
+import { promisify } from "node:util";
+
+// shared/settings.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+// shared/announce.ts
+var stderrAnnounced = /* @__PURE__ */ new Set();
+function announce(ctx, message, level, reason = message) {
+  if (ctx?.hasUI === false) {
+    if (stderrAnnounced.has(reason)) return;
+    stderrAnnounced.add(reason);
+    try {
+      process.stderr.write(`${message}
+`);
+    } catch {
+    }
+    return;
+  }
+  try {
+    ctx?.ui?.notify?.(message, level);
+  } catch {
+  }
+}
+
+// shared/settings.ts
+var announcedConfigErrors = /* @__PURE__ */ new Set();
+function readConfig(path, ctx) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (!announcedConfigErrors.has(path)) {
+      announcedConfigErrors.add(path);
+      const message = error instanceof Error ? error.message : String(error);
+      announce(ctx, `settings: could not parse ${path} (${message}); using defaults.`, "warning", `settings-parse:${path}`);
+    }
+    return {};
+  }
+}
+function resolveSettings(name, definitions, context, runtime = {}) {
+  const environment = runtime.environment ?? process.env;
+  const globalPath = join(runtime.agentDir ?? getAgentDir(), `${name}.json`);
+  const projectPath = join(context.cwd, CONFIG_DIR_NAME, `${name}.json`);
+  const globalConfig = readConfig(globalPath, context);
+  const projectConfig = context.isProjectTrusted() ? readConfig(projectPath, context) : {};
+  const resolved = {};
+  for (const key of Object.keys(definitions)) {
+    const definition = definitions[key];
+    let value = definition.default;
+    let provenance = { source: "default" };
+    if (definition.discover) {
+      try {
+        const discovered = definition.discover();
+        if (discovered !== void 0) {
+          value = discovered.value;
+          provenance = { source: "discovered", name: definition.discoverName ?? "discovery" };
+        }
+      } catch {
+      }
+    }
+    if (Object.hasOwn(globalConfig, key)) {
+      value = globalConfig[key];
+      provenance = { source: "global", path: globalPath };
+    }
+    if (Object.hasOwn(projectConfig, key)) {
+      value = projectConfig[key];
+      provenance = { source: "project", path: projectPath };
+    }
+    const environmentValue = environment[definition.env];
+    if (environmentValue !== void 0) {
+      value = definition.parseEnv ? definition.parseEnv(environmentValue) : environmentValue;
+      provenance = { source: "environment", name: definition.env };
+    }
+    resolved[key] = { value, provenance };
+  }
+  return resolved;
+}
+
+// extensions/cmem/cmem.ts
+var execFileAsync = promisify(execFile);
+var PLATFORM_SOURCE = "pi-agent";
+var DEFAULT_WORKER_PORT = 37777;
+var WORKER_TIMEOUT_MS = 8e3;
+var CHROMA_TIMEOUT_MS = 3e4;
+var MAX_OBSERVATION_CHARS = 1e3;
+var MAX_SEARCH_LIMIT = 100;
+var SESSION_COMPLETE_DELAY_MS = 3e3;
+var CLAUDE_MEM_SETTINGS_DESCRIPTION = "claude-mem's own settings (CLAUDE_MEM_WORKER_";
+function readClaudeMemSetting(key) {
+  const dir = process.env.CLAUDE_MEM_DATA_DIR || join2(homedir(), ".claude-mem");
+  try {
+    const raw = JSON.parse(readFileSync2(join2(dir, "settings.json"), "utf8"));
+    return raw[key];
+  } catch {
+    return void 0;
+  }
+}
+function discoverWorkerHost() {
+  const value = readClaudeMemSetting("CLAUDE_MEM_WORKER_HOST");
+  return typeof value === "string" && value ? { value } : void 0;
+}
+function discoverWorkerPort() {
+  const value = readClaudeMemSetting("CLAUDE_MEM_WORKER_PORT");
+  if (typeof value === "number" && Number.isFinite(value)) return { value };
+  if (typeof value === "string") {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isFinite(parsed)) return { value: parsed };
+  }
+  return void 0;
+}
+var SETTING_DEFINITIONS = {
+  disabled: { default: false, env: "PI_CMEM_DISABLED", parseEnv: (value) => value === "1" },
+  capture: { default: true, env: "PI_CMEM_CAPTURE", parseEnv: (value) => value !== "0" },
+  inject: { default: false, env: "PI_CMEM_INJECT", parseEnv: (value) => value === "1" },
+  workerHost: {
+    default: "127.0.0.1",
+    env: "PI_CMEM_WORKER_HOST",
+    discover: discoverWorkerHost,
+    discoverName: `${CLAUDE_MEM_SETTINGS_DESCRIPTION}HOST)`
+  },
+  workerPort: {
+    default: DEFAULT_WORKER_PORT,
+    env: "PI_CMEM_WORKER_PORT",
+    parseEnv: Number,
+    discover: discoverWorkerPort,
+    discoverName: `${CLAUDE_MEM_SETTINGS_DESCRIPTION}PORT)`
+  },
+  project: { default: "", env: "PI_CMEM_PROJECT" },
+  fallbackPath: { default: "", env: "PI_CMEM_FALLBACK_PATH" }
+};
+var disabled = false;
+var captureEnabled = true;
+var injectEnabled = false;
+var host = "127.0.0.1";
+var port = DEFAULT_WORKER_PORT;
+var configuredProject = "";
+var fallbackChromaScript = "";
+function baseUrl() {
+  return `http://${host}:${port}`;
+}
+function projectName(cwd) {
+  if (configuredProject) return configuredProject;
+  return basename(cwd) || "unknown";
+}
+function withTimeout(ms) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  return { signal: controller.signal, clear: () => clearTimeout(timer) };
+}
+async function workerGetText(path, signal) {
+  const timeout = withTimeout(WORKER_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${baseUrl()}${path}`, { signal: signal ? AbortSignal.any([signal, timeout.signal]) : timeout.signal });
+    if (!res.ok) return null;
+    return await res.text();
+  } catch {
+    return null;
+  } finally {
+    timeout.clear();
+  }
+}
+async function workerPost(path, body) {
+  const timeout = withTimeout(WORKER_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${baseUrl()}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: timeout.signal
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    timeout.clear();
+  }
+}
+function workerPostFireAndForget(path, body) {
+  fetch(`${baseUrl()}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  }).catch(() => {
+  });
+}
+function workerAlive() {
+  return workerGetText("/api/health").then((v) => v !== null);
+}
+async function searchViaWorker(query, limit, project, signal) {
+  const params = new URLSearchParams({ query, limit: String(limit), project });
+  const text = await workerGetText(`/api/search?${params.toString()}`, signal);
+  return text && text.trim() ? text : null;
+}
+async function searchViaChromaScript(query, limit, signal) {
+  if (!fallbackChromaScript || !existsSync2(fallbackChromaScript)) {
+    throw new Error(`memory recall unavailable: worker unreachable at ${baseUrl()} and no Chroma fallback is configured`);
+  }
+  const { stdout } = await execFileAsync(
+    "python3",
+    [fallbackChromaScript, query, "--limit", String(limit)],
+    {
+      timeout: CHROMA_TIMEOUT_MS,
+      maxBuffer: 8 * 1024 * 1024,
+      signal,
+      // Run from $HOME, not the session cwd: a stray module in the working directory
+      // (e.g. an enum.py left in /tmp) shadows Python's stdlib and crashes chromadb's import.
+      cwd: homedir()
+    }
+  );
+  return stdout.trim() || "No matching memories found.";
+}
+var contentSessionId = null;
+var sessionProject = "unknown";
+var sessionCwd = process.cwd();
+var workerHealthy = true;
+function observationPayload(toolName, input, responseText) {
+  return {
+    contentSessionId,
+    tool_name: toolName,
+    tool_input: input ?? {},
+    tool_response: responseText.length > MAX_OBSERVATION_CHARS ? `${responseText.slice(0, MAX_OBSERVATION_CHARS - 12)} [truncated]` : responseText,
+    cwd: sessionCwd,
+    platformSource: PLATFORM_SOURCE
+  };
+}
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.filter((b) => !!b && typeof b === "object" && b.type === "text").map((b) => b.text ?? "").join("\n");
+}
+function lastAssistantText(messages) {
+  if (!Array.isArray(messages)) return "";
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg?.role === "assistant") return textOf(msg.content);
+  }
+  return "";
+}
+function piCmemExtension(pi) {
+  let preflightAnnounced = false;
+  pi.on("session_start", async (_event, ctx) => {
+    const resolved = resolveSettings("pi-cmem", SETTING_DEFINITIONS, ctx);
+    disabled = resolved.disabled.value;
+    captureEnabled = !disabled && resolved.capture.value;
+    injectEnabled = !disabled && resolved.inject.value;
+    host = resolved.workerHost.value;
+    port = resolved.workerPort.value;
+    configuredProject = resolved.project.value;
+    fallbackChromaScript = resolved.fallbackPath.value;
+    preflightAnnounced = false;
+    if (disabled) return;
+    sessionCwd = ctx.cwd;
+    sessionProject = projectName(ctx.cwd);
+    const piSession = typeof ctx.sessionManager?.getSessionId === "function" ? ctx.sessionManager.getSessionId() : null;
+    contentSessionId = piSession || `pi-${sessionProject}-${Date.now()}`;
+    workerHealthy = await workerAlive();
+    if (!workerHealthy && !preflightAnnounced) {
+      const recallCost = fallbackChromaScript && existsSync2(fallbackChromaScript) ? "recall uses the slower Chroma fallback" : "recall has no fallback";
+      const discoveredKeys = [
+        resolved.workerHost.provenance.source === "discovered" && "host",
+        resolved.workerPort.provenance.source === "discovered" && "port"
+      ].filter((key) => typeof key === "string");
+      const discoveryNote = discoveredKeys.length ? ` (${discoveredKeys.join(" and ")} discovered from claude-mem's own settings)` : "";
+      announce(
+        ctx,
+        `pi-cmem: claude-mem worker unreachable at ${baseUrl()}${discoveryNote}; capture and context injection are unavailable, and ${recallCost}`,
+        "warning",
+        "pi-cmem:worker-unreachable"
+      );
+      preflightAnnounced = true;
+    }
+    pi.appendEntry("pi-cmem-session", { contentSessionId, project: sessionProject, worker: baseUrl() });
+  });
+  pi.on("before_agent_start", async (event) => {
+    if (!captureEnabled || !contentSessionId) return;
+    const res = await workerPost("/api/sessions/init", {
+      contentSessionId,
+      project: sessionProject,
+      prompt: event.prompt || "pi session",
+      platformSource: PLATFORM_SOURCE
+    });
+    workerHealthy = res !== null;
+  });
+  pi.on("context", async (event) => {
+    if (!injectEnabled || !contentSessionId || !workerHealthy) return;
+    const digest = await workerGetText(`/api/context/inject?projects=${encodeURIComponent(sessionProject)}`);
+    if (!digest || !digest.trim()) return;
+    return {
+      messages: [
+        ...event.messages,
+        {
+          role: "user",
+          content: [{ type: "text", text: `<pi-cmem-context>
+${digest}
+</pi-cmem-context>` }]
+        }
+      ]
+    };
+  });
+  pi.on("tool_result", (event) => {
+    if (!captureEnabled || !contentSessionId || !workerHealthy) return;
+    const toolName = event.toolName;
+    if (!toolName || toolName === "memory_recall") return;
+    workerPostFireAndForget("/api/sessions/observations", observationPayload(toolName, event.input, textOf(event.content)));
+  });
+  pi.on("agent_end", async (event) => {
+    if (!captureEnabled || !contentSessionId || !workerHealthy) return;
+    await workerPost("/api/sessions/summarize", {
+      contentSessionId,
+      last_assistant_message: lastAssistantText(event.messages),
+      platformSource: PLATFORM_SOURCE
+    });
+    const sid = contentSessionId;
+    setTimeout(() => {
+      workerPostFireAndForget("/api/sessions/complete", { contentSessionId: sid, platformSource: PLATFORM_SOURCE });
+    }, SESSION_COMPLETE_DELAY_MS);
+  });
+  pi.on("session_compact", () => {
+  });
+  pi.on("session_shutdown", () => {
+    contentSessionId = null;
+  });
+  pi.registerTool({
+    name: "memory_recall",
+    label: "Memory Recall",
+    description: "Search cross-session persistent memory (claude-mem: shared across Claude Code, Codex and Pi). Use when the user asks about previous work, or when you need context on how something was done before.",
+    promptSnippet: "Search cross-session persistent memory of past work",
+    promptGuidelines: [
+      "Use memory_recall before asking the user to re-explain earlier work or past decisions.",
+      "Batch related questions into one query, then fetch only the relevant results."
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Natural language search query" }),
+      limit: Type.Optional(
+        Type.Number({ description: "Max results to return (default 5, max 100)" })
+      ),
+      project: Type.Optional(
+        Type.String({ description: "Restrict to one project name (default: current repo, then all projects)" })
+      )
+    }),
+    async execute(_toolCallId, params, signal) {
+      const limit = Math.min(Math.max(1, Math.floor(params.limit ?? 5)), MAX_SEARCH_LIMIT);
+      const query = String(params.query ?? "").trim();
+      if (!query) throw new Error("memory_recall: query must not be empty");
+      const scoped = params.project || sessionProject;
+      const scoped_ = await searchViaWorker(query, limit, scoped, signal);
+      if (scoped_) return { content: [{ type: "text", text: scoped_ }], details: {} };
+      const unscoped = await workerGetText(
+        `/api/search?query=${encodeURIComponent(query)}&limit=${limit}`,
+        signal
+      );
+      if (unscoped && unscoped.trim()) return { content: [{ type: "text", text: unscoped }], details: {} };
+      if (await workerAlive()) {
+        return { content: [{ type: "text", text: "No matching memories found." }], details: {} };
+      }
+      return {
+        content: [{ type: "text", text: await searchViaChromaScript(query, limit, signal) }],
+        details: { source: "chroma-fallback" }
+      };
+    }
+  });
+  pi.registerCommand("memory-status", {
+    description: "Show claude-mem bridge status (worker, project, capture/inject state)",
+    handler: async (_args, ctx) => {
+      const health = await workerGetText("/api/health");
+      if (!health) {
+        announce(ctx, `pi-cmem: claude-mem worker unreachable at ${baseUrl()} (recall falls back to Chroma)`, "warning");
+        return;
+      }
+      let version = "?";
+      try {
+        version = String(JSON.parse(health).version ?? "?");
+      } catch {
+      }
+      announce(
+        ctx,
+        `pi-cmem: worker v${version} @ ${baseUrl()} | project: ${sessionProject} | session: ${contentSessionId ?? "none"} | capture: ${captureEnabled ? "on" : "off"} | inject: ${injectEnabled ? "on" : "off"}`,
+        "info"
+      );
+    }
+  });
+}
+export {
+  piCmemExtension as default
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "pi-cmem",
+  "version": "0.1.0",
+  "description": "Bridge Pi sessions to a shared claude-mem worker.",
+  "type": "module",
+  "main": "./cmem.js",
+  "exports": "./cmem.js",
+  "files": [
+    "cmem.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ezoushen/pi-extensions.git",
+    "directory": "extensions/cmem"
+  },
+  "homepage": "https://github.com/ezoushen/pi-extensions/tree/main/extensions/cmem#readme",
+  "bugs": {
+    "url": "https://github.com/ezoushen/pi-extensions/issues"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./cmem.js"
+    ]
+  }
+}