@chendpoc/pi-memory 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+/** Wire types mirroring Kocoro internal/memory/types.go (TLM sidecar contract). */
+export type QueryMode = "direct_relation" | "path_query" | "typed_neighborhood";
+export interface QueryIntent {
+    mode: QueryMode;
+    anchor_mentions: string[];
+    relation_constraints?: string[];
+    candidate_type?: string | null;
+    scope_filter?: string[];
+    target_slot?: "" | "head" | "tail";
+    time_window?: string | null;
+    evidence_budget?: number;
+    result_limit?: number;
+}
+export interface QueryRequest {
+    intent: QueryIntent;
+    user_id?: string | null;
+    request_id?: string | null;
+}
+export interface HopRecord {
+    from_entity_id: string;
+    from_label: string;
+    relation: string;
+    direction: string;
+    to_entity_id: string;
+    to_label: string;
+    supporting_event_ids: string[];
+}
+export interface QueryCandidate {
+    value: string;
+    score: number;
+    evidence: string;
+    supporting_event_ids: string[];
+    support_count?: number | null;
+    distinct_session_count?: number | null;
+    entity_id?: string | null;
+    scope?: string | null;
+    observed_path?: HopRecord[];
+    path_collision_count?: number;
+}
+export interface MemoryCandidateGroup {
+    value: string;
+    score: number;
+    evidence: string;
+    support_count: number;
+    supporting_event_ids: string[];
+    entity_ids: string[];
+    scopes: string[];
+    via_relations: string[];
+    via_anchor_entity_ids: string[];
+    observed_path: HopRecord[];
+    path_collision_count: number;
+}
+export interface MemoryBlock {
+    groups: MemoryCandidateGroup[];
+    no_data_reason?: string | null;
+    notes: string[];
+}
+export interface Warning {
+    code: string;
+    message: string;
+}
+export interface ErrorObject {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export declare function errorSubCode(err: ErrorObject | null | undefined): string;
+export interface ResponseEnvelope {
+    protocol_version: number;
+    bundle_version?: string;
+    bundle_created_at?: string | null;
+    bundle_dir?: string;
+    request_id: string;
+    candidates: QueryCandidate[];
+    memory_block?: MemoryBlock | null;
+    warnings: Warning[];
+    reason: string;
+    error?: ErrorObject | null;
+    latency_ms: number;
+}
+export interface ReloadResponse {
+    protocol_version: number;
+    request_id: string;
+    swapped: boolean;
+    trigger: string;
+    reason: string;
+    previous_bundle_dir?: string | null;
+    current_bundle_dir?: string | null;
+    reload_duration_ms: number;
+    warnings: Warning[];
+    error?: ErrorObject | null;
+}
+export interface HealthPayload {
+    ready: boolean;
+    compatibility: string;
+    bundle_version?: string;
+    bundle_created_at?: string | null;
+    bundle_dir?: string;
+    last_reload_age_secs?: number | null;
+    last_reload_trigger?: string | null;
+    protocol_version: number;
+    uptime_secs: number;
+    error?: ErrorObject | null;
+    status_message?: string;
+}
+export type ServiceStatus = "disabled" | "initializing" | "ready" | "degraded" | "unavailable";
+export interface MemoryRecallArgs {
+    mode?: string;
+    anchor_mentions: string[];
+    relation_constraints?: string[];
+    candidate_type?: string | null;
+    scope_filter?: string[];
+    target_slot?: string;
+    time_window?: string | null;
+    evidence_budget?: number;
+    result_limit?: number;
+}
+export interface ToolResult {
+    content: string;
+    isError?: boolean;
+}
+export type ErrorClass = "ok" | "retryable" | "permanent" | "unavailable";
+export interface MemoryQuerier {
+    status(): ServiceStatus;
+    query(intent: QueryIntent, signal?: AbortSignal): Promise<{
+        env: ResponseEnvelope | null;
+        errorClass: ErrorClass;
+        transportError?: Error;
+    }>;
+}
+export interface FallbackQuery {
+    sessionKeyword(query: string, limit: number): Promise<unknown[]>;
+    memoryFileSnippet(query: string): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/** Wire types mirroring Kocoro internal/memory/types.go (TLM sidecar contract). */
+export function errorSubCode(err) {
+    if (!err?.details)
+        return "";
+    const v = err.details.sub_code;
+    return typeof v === "string" ? v : "";
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,mFAAmF;AA+EnF,MAAM,UAAU,YAAY,CAAC,GAAmC;IAC9D,IAAI,CAAC,GAAG,EAAE,OAAO;QAAE,OAAO,EAAE,CAAC;IAC7B,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC/B,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@chendpoc/pi-memory",
+  "version": "0.1.0",
+  "description": "Local episodic memory for Pi agent — TLM sidecar + memory_recall (mode B)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./extension": {
+      "types": "./dist/pi-extension.d.ts",
+      "import": "./dist/pi-extension.js"
+    }
+  },
+  "bin": {
+    "pi-memory": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-agent",
+    "tlm",
+    "episodic-memory",
+    "sidecar"
+  ],
+  "license": "MIT",
+  "author": "chendpoc",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chendpoc/pi-memory.git"
+  },
+  "homepage": "https://github.com/chendpoc/pi-memory#readme",
+  "pi": {
+    "extensions": [
+      "./src/pi-extension.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^12.10.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.10.0",
+    "typebox": "*",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "allowScripts": {
+    "better-sqlite3@12.11.1": true
+  }
+}

package/src/adapters/piComplete.ts

@@ -0,0 +1,233 @@
+import { complete, getEnvApiKey, getModels } from "@earendil-works/pi-ai/compat";
+import type { Api, Model, ProviderEnv, ToolCall } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  COMPILE_MEMORY_INTENTS_PARAMETERS,
+  MEMORY_HELPER_TOOL_NAME,
+  type CompileMemoryIntentsResult,
+  type MemoryHelperLLM,
+} from "../preflight/detectIntents.js";
+import type { LLMClient } from "../trainer/llmExtractor.js";
+
+export const DEFAULT_HELPER_PROVIDER = "deepseek";
+export const DEFAULT_HELPER_MODEL = "deepseek-v4-flash";
+
+const CompileMemoryIntentsParams = Type.Unsafe(COMPILE_MEMORY_INTENTS_PARAMETERS);
+
+export function parseModelSpec(
+  spec: string | boolean | undefined,
+  defaultProvider = DEFAULT_HELPER_PROVIDER,
+  defaultModelId = DEFAULT_HELPER_MODEL,
+): { provider: string; modelId: string } {
+  if (typeof spec !== "string" || !spec.trim()) {
+    return { provider: defaultProvider, modelId: defaultModelId };
+  }
+  const trimmed = spec.trim();
+  const slash = trimmed.indexOf("/");
+  if (slash === -1) {
+    return { provider: defaultProvider, modelId: trimmed };
+  }
+  return {
+    provider: trimmed.slice(0, slash),
+    modelId: trimmed.slice(slash + 1),
+  };
+}
+
+async function resolveModelAuth(
+  ctx: ExtensionContext,
+  provider: string,
+  modelId: string,
+): Promise<{ model: Model<Api>; apiKey: string; headers?: Record<string, string>; env?: ProviderEnv } | null> {
+  const model = ctx.modelRegistry.find(provider, modelId);
+  if (!model) return null;
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok || !auth.apiKey) return null;
+
+  return {
+    model,
+    apiKey: auth.apiKey,
+    headers: auth.headers,
+    env: auth.env,
+  };
+}
+
+function extractTextFromResponse(content: Array<{ type: string; text?: string }>): string {
+  return content
+    .filter((block): block is { type: "text"; text: string } => block.type === "text")
+    .map((block) => block.text)
+    .join("\n");
+}
+
+function findToolCall(
+  content: Array<{ type: string; name?: string; arguments?: Record<string, unknown> }>,
+  toolName: string,
+): ToolCall | null {
+  for (const block of content) {
+    if (block.type === "toolCall" && block.name === toolName && block.arguments) {
+      return block as ToolCall;
+    }
+  }
+  return null;
+}
+
+function buildMemoryHelperLLM(
+  resolved: NonNullable<Awaited<ReturnType<typeof resolveModelAuth>>>,
+): MemoryHelperLLM {
+  return {
+    async compileIntents(text: string, signal?: AbortSignal): Promise<CompileMemoryIntentsResult> {
+      const response = await complete(
+        resolved.model,
+        {
+          messages: [
+            {
+              role: "user",
+              content: [
+                {
+                  type: "text",
+                  text: `Analyze whether the user message requires recalling private episodic memory.\n\n<message>\n${text}\n</message>`,
+                },
+              ],
+              timestamp: Date.now(),
+            },
+          ],
+          tools: [
+            {
+              name: MEMORY_HELPER_TOOL_NAME,
+              description:
+                "Decide whether to recall private episodic memory and compile structured query intents.",
+              parameters: CompileMemoryIntentsParams,
+            },
+          ],
+        },
+        {
+          apiKey: resolved.apiKey,
+          headers: resolved.headers,
+          env: resolved.env,
+          signal,
+          toolChoice: { type: "tool", name: MEMORY_HELPER_TOOL_NAME },
+        },
+      );
+
+      const toolCall = findToolCall(response.content, MEMORY_HELPER_TOOL_NAME);
+      if (toolCall?.arguments) {
+        return toolCall.arguments as CompileMemoryIntentsResult;
+      }
+
+      const raw = extractTextFromResponse(response.content);
+      if (!raw.trim()) {
+        return { should_recall: false, intents: [] };
+      }
+      return JSON.parse(raw) as CompileMemoryIntentsResult;
+    },
+  };
+}
+
+/** Resolve helper LLM when model + auth are available; otherwise null (regex-only preflight). */
+export async function resolveMemoryHelperLLM(
+  ctx: ExtensionContext,
+  modelSpec: string | boolean | undefined,
+): Promise<MemoryHelperLLM | null> {
+  const { provider, modelId } = parseModelSpec(modelSpec);
+  const resolved = await resolveModelAuth(ctx, provider, modelId);
+  if (!resolved) return null;
+  return buildMemoryHelperLLM(resolved);
+}
+
+/** @alias resolveMemoryHelperLLM */
+export const createMemoryHelperLLM = resolveMemoryHelperLLM;
+
+export function createPiLLMClient(
+  ctx: ExtensionContext,
+  modelSpec: string | boolean | undefined,
+): LLMClient | null {
+  const { provider, modelId } = parseModelSpec(modelSpec);
+
+  return {
+    async complete(prompt: string): Promise<string> {
+      const resolved = await resolveModelAuth(ctx, provider, modelId);
+      if (!resolved) {
+        throw new Error(`LLM model not available: ${provider}/${modelId}`);
+      }
+
+      const response = await complete(
+        resolved.model,
+        {
+          messages: [
+            {
+              role: "user",
+              content: [{ type: "text", text: prompt }],
+              timestamp: Date.now(),
+            },
+          ],
+        },
+        {
+          apiKey: resolved.apiKey,
+          headers: resolved.headers,
+          env: resolved.env,
+          maxTokens: 8192,
+        },
+      );
+
+      const text = extractTextFromResponse(response.content);
+      if (!text.trim()) {
+        throw new Error("LLM response was empty");
+      }
+      return text;
+    },
+  };
+}
+
+/** Standalone LLM client for CLI usage without ExtensionContext. */
+export function createStandaloneLLMClient(
+  modelSpec?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): LLMClient {
+  const { provider, modelId } = parseModelSpec(modelSpec);
+  const providerEnv = toProviderEnv(env);
+  const model = getModels(provider as Parameters<typeof getModels>[0]).find((m) => m.id === modelId);
+  if (!model) {
+    throw new Error(`Model not found: ${provider}/${modelId}`);
+  }
+
+  const apiKey = getEnvApiKey(provider, providerEnv);
+  if (!apiKey) {
+    throw new Error(`No API key for ${provider} — set the provider env var or use regex extractor`);
+  }
+
+  return {
+    async complete(prompt: string): Promise<string> {
+      const response = await complete(
+        model,
+        {
+          messages: [
+            {
+              role: "user",
+              content: [{ type: "text", text: prompt }],
+              timestamp: Date.now(),
+            },
+          ],
+        },
+        {
+          apiKey,
+          maxTokens: 8192,
+          env: providerEnv,
+        },
+      );
+
+      const text = extractTextFromResponse(response.content);
+      if (!text.trim()) {
+        throw new Error("LLM response was empty");
+      }
+      return text;
+    },
+  };
+}
+
+function toProviderEnv(env: NodeJS.ProcessEnv): ProviderEnv {
+  return Object.fromEntries(
+    Object.entries(env).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  );
+}

package/src/bundle/install.ts

@@ -0,0 +1,206 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { BundleManifest } from "../sidecar/bundle.js";
+
+export interface InstallBundleOptions {
+  bundleRoot: string;
+  sourceDir: string;
+  /** Number of old bundles to keep after install (default 3). */
+  retain?: number;
+}
+
+export interface InstallBundleResult {
+  bundle_ts: string;
+  bundle_version: string;
+  installed_dir: string;
+  files_copied: number;
+}
+
+/**
+ * Enforces [0.4.0, 0.7.0) — producers guarantee additive minor bumps in this
+ * range; breaking schema changes move to 0.7.0+ to trip this gate.
+ * Ported from Kocoro internal/memory/bundle.go versionInRange.
+ */
+export function versionInRange(v: string): boolean {
+  const parts = v.split(".");
+  if (parts.length !== 3) return false;
+  const [maj, min, pat] = parts.map(Number);
+  if (maj !== 0 || isNaN(min!) || isNaN(pat!)) return false;
+  if (min! < 4 || min! >= 7) return false;
+  return pat! >= 0;
+}
+
+/**
+ * Keep the newest `keep` bundle dirs plus the current symlink target.
+ * Best-effort — failures are silently ignored.
+ * Ported from Kocoro internal/memory/bundle.go Puller.retain.
+ */
+export async function retainBundles(bundleRoot: string, keep: number): Promise<void> {
+  const bundlesDir = path.join(bundleRoot, "bundles");
+  let names: string[];
+  try {
+    names = await fs.readdir(bundlesDir);
+  } catch {
+    return;
+  }
+  const dirs: string[] = [];
+  for (const name of names) {
+    try {
+      const st = await fs.stat(path.join(bundlesDir, name));
+      if (st.isDirectory()) dirs.push(name);
+    } catch { /* skip unreadable */ }
+  }
+  dirs.sort().reverse();
+  if (dirs.length <= keep) return;
+
+  let currentTarget = "";
+  try {
+    const target = await fs.readlink(path.join(bundleRoot, "current"));
+    currentTarget = path.basename(target);
+  } catch { /* no current pointer */ }
+
+  const keepSet = new Set<string>();
+  for (let i = 0; i < Math.min(keep, dirs.length); i++) {
+    keepSet.add(dirs[i]!);
+  }
+  if (currentTarget) keepSet.add(currentTarget);
+
+  for (const d of dirs) {
+    if (!keepSet.has(d)) {
+      await fs.rm(path.join(bundlesDir, d), { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+/**
+ * Path sandboxing rules from Kocoro bundle.go validateManifestPath (§4.2).
+ */
+export function validateManifestPath(rel: string, stagingDir: string): string | null {
+  if (!rel) return "empty path";
+  if (rel.includes("\0")) return "null byte in path";
+  if (path.isAbsolute(rel)) return "absolute path";
+  const cleaned = path.normalize(rel);
+  if (
+    cleaned === ".." ||
+    cleaned.startsWith(`..${path.sep}`) ||
+    cleaned.includes(`${path.sep}..`)
+  ) {
+    return "contains parent traversal";
+  }
+  const abs = path.join(stagingDir, cleaned);
+  const cleanedAbs = path.normalize(abs);
+  const prefix = path.normalize(stagingDir) + path.sep;
+  if (!cleanedAbs.startsWith(prefix)) {
+    return "escapes staging dir";
+  }
+  return null;
+}
+
+async function sha256File(filePath: string): Promise<string> {
+  const data = await fs.readFile(filePath);
+  return createHash("sha256").update(data).digest("hex");
+}
+
+/**
+ * Points <bundleRoot>/current at finalDir. On Windows uses a directory junction
+ * (unprivileged, no Developer Mode needed — os.Symlink would fail with
+ * ERROR_PRIVILEGE_NOT_HELD on stock hosts). On POSIX uses atomic tmp-symlink +
+ * rename. Ported from Kocoro bundle_link_{unix,windows}.go.
+ */
+async function swapCurrent(bundleRoot: string, finalDir: string): Promise<void> {
+  const currentLink = path.join(bundleRoot, "current");
+
+  if (process.platform === "win32") {
+    try { await fs.rm(currentLink, { recursive: true, force: true }); } catch { /* absent */ }
+    await fs.symlink(finalDir, currentLink, "junction");
+    return;
+  }
+
+  const tmpLink = path.join(bundleRoot, "current.tmp");
+  try { await fs.unlink(tmpLink); } catch { /* absent */ }
+  await fs.symlink(finalDir, tmpLink);
+  await fs.rename(tmpLink, currentLink);
+}
+
+/**
+ * Install a local bundle directory into bundleRoot (staging → bundles/<ts> → current).
+ * Verifies per-file sha256 when manifest lists hashes.
+ */
+export async function installBundle(
+  opts: InstallBundleOptions,
+): Promise<InstallBundleResult> {
+  const sourceDir = path.resolve(opts.sourceDir);
+  const bundleRoot = path.resolve(opts.bundleRoot);
+
+  const manifestPath = path.join(sourceDir, "manifest.json");
+  const raw = await fs.readFile(manifestPath, "utf8");
+  const manifest = JSON.parse(raw) as BundleManifest;
+
+  if (!manifest.bundle_ts?.trim()) {
+    throw new Error("manifest missing bundle_ts");
+  }
+  if (!versionInRange(manifest.bundle_version ?? "")) {
+    throw new Error(
+      `bundle_version "${manifest.bundle_version}" outside supported range [0.4.0, 0.7.0)`,
+    );
+  }
+
+  await fs.mkdir(bundleRoot, { recursive: true, mode: 0o700 });
+
+  const staging = path.join(bundleRoot, "staging", manifest.bundle_ts);
+  await fs.rm(staging, { recursive: true, force: true });
+  await fs.mkdir(staging, { recursive: true, mode: 0o700 });
+
+  let filesCopied = 0;
+  for (const f of manifest.files ?? []) {
+    const err = validateManifestPath(f.path, staging);
+    if (err) {
+      await fs.rm(staging, { recursive: true, force: true });
+      throw new Error(`unsafe manifest path ${f.path}: ${err}`);
+    }
+    const src = path.join(sourceDir, path.normalize(f.path));
+    const dest = path.join(staging, path.normalize(f.path));
+    await fs.mkdir(path.dirname(dest), { recursive: true, mode: 0o700 });
+    await fs.copyFile(src, dest, fs.constants.COPYFILE_EXCL).catch(async () => {
+      await fs.copyFile(src, dest);
+    });
+
+    if (f.sha256) {
+      const got = await sha256File(dest);
+      if (got !== f.sha256) {
+        await fs.rm(staging, { recursive: true, force: true });
+        throw new Error(`sha256 mismatch on ${f.path}: got ${got} want ${f.sha256}`);
+      }
+    }
+    filesCopied++;
+  }
+
+  // Copy manifest itself if not listed in files[]
+  const manifestDest = path.join(staging, "manifest.json");
+  try {
+    await fs.access(manifestDest);
+  } catch {
+    await fs.copyFile(manifestPath, manifestDest);
+  }
+
+  const bundlesDir = path.join(bundleRoot, "bundles");
+  await fs.mkdir(bundlesDir, { recursive: true, mode: 0o700 });
+  const finalDir = path.join(bundlesDir, manifest.bundle_ts);
+  await fs.rm(finalDir, { recursive: true, force: true });
+  await fs.rename(staging, finalDir);
+  await swapCurrent(bundleRoot, finalDir);
+
+  const keep = opts.retain ?? 3;
+  if (keep > 0) {
+    await retainBundles(bundleRoot, keep);
+  }
+
+  return {
+    bundle_ts: manifest.bundle_ts,
+    bundle_version: manifest.bundle_version,
+    installed_dir: finalDir,
+    files_copied: filesCopied,
+  };
+}