@chendpoc/pi-memory 0.1.12 → 0.2.0

package/src/sidecar/process.ts

@@ -1,160 +0,0 @@
-import { access, constants } from "node:fs/promises";
-import fs from "node:fs";
-import path from "node:path";
-import { spawn, type ChildProcess } from "node:child_process";
-
-import type { MemoryConfig } from "../config.js";
-import { SidecarClient } from "./client.js";
-
-export class SidecarProcess {
-  private child: ChildProcess | null = null;
-  private readonly client: SidecarClient;
-
-  constructor(private readonly cfg: MemoryConfig) {
-    this.client = new SidecarClient(
-      cfg.socketPath,
-      Math.min(cfg.clientRequestTimeoutMs, 5_000),
-    );
-  }
-
-  getClient(): SidecarClient {
-    return this.client;
-  }
-
-  async resolveBinary(): Promise<string> {
-    const bin = this.cfg.tlmPath;
-    if (path.isAbsolute(bin)) {
-      await access(bin, constants.X_OK);
-      return bin;
-    }
-    const resolved = await which(bin);
-    if (!resolved) throw new Error(`${bin} not found in PATH`);
-    return resolved;
-  }
-
-  async spawn(): Promise<void> {
-    const bin = await this.resolveBinary().catch(() => {
-      throw new Error("memory: tlm binary not found");
-    });
-
-    if (this.cfg.socketPath) {
-      try {
-        fs.unlinkSync(this.cfg.socketPath);
-      } catch {
-        /* absent */
-      }
-    }
-
-    const args = [
-      "serve",
-      "--socket",
-      this.cfg.socketPath,
-      "--bundle-root",
-      this.cfg.bundleRoot,
-    ];
-
-    this.child = spawn(bin, args, {
-      stdio: "ignore",
-      detached: process.platform !== "win32",
-    });
-
-    this.child.on("error", () => {
-      /* handled by waitReady timeout */
-    });
-
-    this.child.unref?.();
-  }
-
-  async waitReady(signal?: AbortSignal): Promise<void> {
-    const deadline = Date.now() + this.cfg.sidecarReadyTimeoutMs;
-    let lastCompat = "";
-    let lastSub = "";
-
-    while (Date.now() < deadline) {
-      if (signal?.aborted) throw signal.reason ?? new Error("aborted");
-
-      try {
-        const h = await this.client.health(signal);
-        lastCompat = h.compatibility ?? "";
-        lastSub = h.error ? String(h.error.details?.sub_code ?? "") : "";
-
-        if (h.ready === true) return;
-        if (h.compatibility === "unknown") return;
-        if (h.compatibility === "incompatible") {
-          // keep polling until ceiling — supervisor classifies schema mismatch
-        }
-      } catch {
-        /* sidecar still starting */
-      }
-
-      await sleep(500, signal);
-    }
-
-    throw new Error(
-      `memory: sidecar ready ceiling exceeded` +
-        (lastCompat === "incompatible" && lastSub
-          ? ` (incompatible: ${lastSub})`
-          : ""),
-    );
-  }
-
-  async stop(): Promise<void> {
-    const child = this.child;
-    this.child = null;
-    if (!child?.pid) return;
-
-    if (process.platform === "win32") {
-      spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"]);
-    } else {
-      try {
-        process.kill(-child.pid, "SIGTERM");
-      } catch {
-        try {
-          child.kill("SIGTERM");
-        } catch {
-          /* already dead */
-        }
-      }
-    }
-
-    await new Promise<void>((resolve) => {
-      const t = setTimeout(resolve, 2_000);
-      child.on("exit", () => {
-        clearTimeout(t);
-        resolve();
-      });
-    });
-  }
-}
-
-async function which(cmd: string): Promise<string | null> {
-  const { execFileSync } = await import("node:child_process");
-  try {
-    const result = execFileSync(
-      process.platform === "win32" ? "where" : "which",
-      [cmd],
-      { encoding: "utf8", timeout: 3_000 },
-    ).trim();
-    return result.split("\n")[0]?.trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(signal.reason ?? new Error("aborted"));
-      return;
-    }
-    const t = setTimeout(resolve, ms);
-    signal?.addEventListener(
-      "abort",
-      () => {
-        clearTimeout(t);
-        reject(signal.reason ?? new Error("aborted"));
-      },
-      { once: true },
-    );
-  });
-}

package/src/tools/memoryAppend.ts

@@ -1,113 +0,0 @@
-import fs from "node:fs/promises";
-import { open } from "node:fs/promises";
-import path from "node:path";
-
-import type { ToolResult } from "../types.js";
-
-export const MEMORY_APPEND_NAME = "memory_append";
-
-export const MEMORY_APPEND_DESCRIPTION =
-  "Append new entries to MEMORY.md. Use this instead of file_write or file_edit for memory updates. " +
-  "Writes are append-only with a simple lock to avoid concurrent clobber.";
-
-export const MEMORY_APPEND_PROMPT_SNIPPET = "Append durable notes to MEMORY.md";
-
-export const MEMORY_APPEND_PROMPT_GUIDELINES = [
-  "Use memory_append to persist user preferences or facts the user explicitly asked to remember — not for transient task state.",
-] as const;
-
-export const MEMORY_APPEND_PARAMETERS = {
-  type: "object",
-  properties: {
-    content: {
-      type: "string",
-      description:
-        "New entries to append (markdown bullet points). Write in English by default.",
-    },
-  },
-  required: ["content"],
-} as const;
-
-const LOCK_RETRIES = 50;
-const LOCK_DELAY_MS = 20;
-
-async function withAppendLock<T>(
-  lockPath: string,
-  fn: () => Promise<T>,
-): Promise<T> {
-  let handle;
-  for (let i = 0; i < LOCK_RETRIES; i++) {
-    try {
-      handle = await open(lockPath, "wx");
-      break;
-    } catch {
-      await new Promise((r) => setTimeout(r, LOCK_DELAY_MS));
-    }
-  }
-  if (!handle) {
-    throw new Error("could not acquire MEMORY.md append lock");
-  }
-  try {
-    return await fn();
-  } finally {
-    await handle.close();
-    await fs.unlink(lockPath).catch(() => {});
-  }
-}
-
-export async function appendToMemoryMd(
-  memoryMdPath: string,
-  content: string,
-): Promise<void> {
-  const trimmed = content.trim();
-  if (!trimmed) {
-    throw new Error("content must not be empty");
-  }
-  await fs.mkdir(path.dirname(memoryMdPath), { recursive: true, mode: 0o700 });
-  const lockPath = `${memoryMdPath}.append.lock`;
-  const block = content.endsWith("\n") ? content : `${content}\n`;
-  await withAppendLock(lockPath, async () => {
-    await fs.appendFile(memoryMdPath, block, { encoding: "utf8", mode: 0o600 });
-  });
-}
-
-export class MemoryAppendTool {
-  constructor(private readonly memoryMdPath: string) {}
-
-  info() {
-    return {
-      name: MEMORY_APPEND_NAME,
-      description: MEMORY_APPEND_DESCRIPTION,
-      parameters: MEMORY_APPEND_PARAMETERS,
-    };
-  }
-
-  async run(argsJson: string): Promise<ToolResult> {
-    let raw: Record<string, unknown>;
-    try {
-      raw = JSON.parse(argsJson) as Record<string, unknown>;
-    } catch (e) {
-      return {
-        content: `invalid arguments: ${e instanceof Error ? e.message : e}`,
-        isError: true,
-      };
-    }
-    const content = typeof raw.content === "string" ? raw.content : "";
-    if (!content.trim()) {
-      return { content: "content must not be empty", isError: true };
-    }
-    try {
-      await appendToMemoryMd(this.memoryMdPath, content);
-      return { content: `appended to ${this.memoryMdPath}` };
-    } catch (e) {
-      return {
-        content: `error appending: ${e instanceof Error ? e.message : e}`,
-        isError: true,
-      };
-    }
-  }
-}
-
-export function createMemoryAppendTool(memoryMdPath: string): MemoryAppendTool {
-  return new MemoryAppendTool(memoryMdPath);
-}

package/src/tools/memoryRecall.ts

@@ -1,388 +0,0 @@
-import { createFallbackQuery } from "../fallback/index.js";
-import { rerankWithLLM, type RerankOptions, type RankedResult } from "../fallback/llmRerank.js";
-import type { SessionSearchHit } from "../fallback/sessionSearch.js";
-import type { FallbackQuery, MemoryQuerier, MemoryRecallArgs, QueryIntent, QueryMode, ResponseEnvelope, ToolResult } from "../types.js";
-
-export const MEMORY_RECALL_NAME = "memory_recall";
-
-export const MEMORY_RECALL_DESCRIPTION =
-  "Read structured episodic memory from the local TLM sidecar — past sessions consolidated into long-term records.\n" +
-  "Modes:\n" +
-  "- direct_relation: one-hop predicate (e.g. \"what did X create?\"). Read groups[].via_relations.\n" +
-  "- path_query: multi-hop / possessive. relation_constraints is the ordered path; inverse hops use ^-1.\n" +
-  "- typed_neighborhood: typed target with exactly one relation. Requires candidate_type.\n\n" +
-  "Ground answers in supporting evidence internally; tell the user \"past records\" / \"以前的记录\", not raw event IDs.";
-
-export const MEMORY_RECALL_PROMPT_SNIPPET =
-  "Query local episodic memory by entity or relationship";
-
-export const MEMORY_RECALL_PROMPT_GUIDELINES = [
-  "Use memory_recall when the user asks about past sessions, people, projects, or decisions stored in long-term memory.",
-  "Use memory_recall for relationship questions (e.g. who is X to me) when implicit preflight did not already answer.",
-] as const;
-
-export const MEMORY_RECALL_PARAMETERS = {
-  type: "object",
-  properties: {
-    mode: {
-      type: "string",
-      enum: ["direct_relation", "path_query", "typed_neighborhood"],
-    },
-    anchor_mentions: { type: "array", items: { type: "string" } },
-    relation_constraints: { type: "array", items: { type: "string" } },
-    candidate_type: { type: "string" },
-    scope_filter: { type: "array", items: { type: "string" } },
-    target_slot: { type: "string", enum: ["head", "tail"] },
-    time_window: { type: "string" },
-    evidence_budget: { type: "integer" },
-    result_limit: { type: "integer" },
-  },
-  required: ["anchor_mentions"],
-} as const;
-
-export class MemoryRecallTool {
-  constructor(
-    private readonly service: MemoryQuerier,
-    private readonly fallback: FallbackQuery | null = null,
-    private readonly rerankOpts: RerankOptions | null = null,
-  ) {}
-
-  info() {
-    return {
-      name: MEMORY_RECALL_NAME,
-      description: MEMORY_RECALL_DESCRIPTION,
-      parameters: MEMORY_RECALL_PARAMETERS,
-    };
-  }
-
-  async run(argsJson: string, signal?: AbortSignal, onProgress?: (msg: string) => void): Promise<ToolResult> {
-    const args = parseArgs(argsJson);
-    if ("error" in args) {
-      return { content: args.error, isError: true };
-    }
-
-    const intent = argsToIntent(args);
-    const validation = validateArgs(args);
-    if (validation) {
-      return { content: validation, isError: true };
-    }
-
-    return this.runIntent(intent, signal, onProgress);
-  }
-
-  async runIntent(intent: QueryIntent, signal?: AbortSignal, onProgress?: (msg: string) => void): Promise<ToolResult> {
-    if (this.service.status() !== "ready") {
-      return this.fallbackResult(intent, "service_unavailable", "fallback");
-    }
-
-    // Emit a progress message if the sidecar takes longer than 500 ms.
-    let progressTimer: ReturnType<typeof setTimeout> | null = null;
-    if (onProgress) {
-      progressTimer = setTimeout(() => {
-        onProgress("Querying episodic memory…");
-      }, 500);
-    }
-
-    let result;
-    try {
-      result = await this.service.query(intent, signal);
-    } finally {
-      if (progressTimer != null) clearTimeout(progressTimer);
-    }
-
-    if (result.transportError || result.errorClass === "unavailable") {
-      return this.fallbackResult(intent, "service_unavailable", "fallback");
-    }
-
-    if (result.errorClass === "retryable") {
-      let retryTimer: ReturnType<typeof setTimeout> | null = null;
-      if (onProgress) {
-        retryTimer = setTimeout(() => onProgress("Retrying memory query…"), 500);
-      }
-      let retryResult;
-      try {
-        await sleep(500, signal);
-        retryResult = await this.service.query(intent, signal);
-      } finally {
-        if (retryTimer != null) clearTimeout(retryTimer);
-      }
-      if (
-        retryResult.transportError ||
-        retryResult.errorClass === "unavailable" ||
-        retryResult.errorClass === "retryable"
-      ) {
-        return this.fallbackResult(intent, "retryable_failed", "fallback_after_retry");
-      }
-      result = retryResult;
-    }
-
-    if (result.errorClass === "permanent") {
-      return permanentResult(result.env);
-    }
-
-    return shapeResult(result.env!);
-  }
-
-  private async fallbackResult(
-    intent: QueryIntent,
-    reason: string,
-    source: string,
-  ): Promise<ToolResult> {
-    const candidates: Record<string, unknown>[] = [];
-    const warnings: Record<string, unknown>[] = [];
-
-    if (this.fallback) {
-      const query = intent.anchor_mentions.map((s) => s.trim()).filter(Boolean).join(" ");
-      const limit = intent.result_limit && intent.result_limit > 0 ? intent.result_limit : 10;
-      try {
-        const hits = await this.fallback.sessionKeyword(query, limit);
-
-        let reranked: RankedResult[] | null = null;
-        if (this.rerankOpts && hits.length > 0) {
-          try {
-            reranked = await rerankWithLLM(
-              query,
-              hits as SessionSearchHit[],
-              this.rerankOpts,
-            );
-          } catch {
-            /* silent fallback to original order */
-          }
-        }
-
-        if (reranked) {
-          for (const r of reranked) {
-            const original = hits[r.index];
-            candidates.push({
-              value: r.summary,
-              score: r.score,
-              evidence: "llm_rerank",
-              ...(typeof original === "object" && original !== null &&
-                "session_id" in (original as Record<string, unknown>)
-                ? { scope: "session_search", session_id: (original as Record<string, unknown>).session_id }
-                : {}),
-            });
-          }
-        } else {
-          for (const h of hits) {
-            candidates.push({
-              value: typeof h === "string" ? h : JSON.stringify(h),
-              evidence: "text_search",
-              ...(typeof h === "object" &&
-              h !== null &&
-              "session_id" in (h as Record<string, unknown>)
-                ? { scope: "session_search" }
-                : {}),
-            });
-          }
-        }
-      } catch (err) {
-        warnings.push({
-          code: "fallback_session_search_failed",
-          message: err instanceof Error ? err.message : String(err),
-        });
-      }
-      try {
-        const snippet = await this.fallback.memoryFileSnippet(query);
-        if (snippet) {
-          candidates.push({
-            value: snippet,
-            evidence: "text_search",
-            scope: "memory_md",
-          });
-        }
-      } catch {
-        /* optional */
-      }
-    }
-
-    const out = {
-      source,
-      evidence_quality: "text_search",
-      bundle_version: null,
-      candidates,
-      warnings,
-      fallback_reason: reason,
-    };
-    return { content: JSON.stringify(out) };
-  }
-}
-
-function parseArgs(argsJson: string): MemoryRecallArgs | { error: string } {
-  let raw: Record<string, unknown>;
-  try {
-    raw = JSON.parse(coerceArgs(argsJson)) as Record<string, unknown>;
-  } catch (e) {
-    return { error: `invalid input: ${e instanceof Error ? e.message : e}` };
-  }
-  const anchor = raw.anchor_mentions;
-  if (!Array.isArray(anchor) || anchor.length === 0) {
-    return { error: "anchor_mentions is required and must be non-empty" };
-  }
-  return raw as unknown as MemoryRecallArgs;
-}
-
-function argsToIntent(a: MemoryRecallArgs): QueryIntent {
-  return {
-    mode: (a.mode as QueryMode) || "direct_relation",
-    anchor_mentions: a.anchor_mentions,
-    relation_constraints: a.relation_constraints,
-    candidate_type: a.candidate_type,
-    scope_filter: a.scope_filter,
-    target_slot: (a.target_slot as QueryIntent["target_slot"]) ?? "",
-    time_window: a.time_window,
-    evidence_budget: a.evidence_budget && a.evidence_budget > 0 ? a.evidence_budget : 5,
-    result_limit: a.result_limit && a.result_limit > 0 ? a.result_limit : 10,
-  };
-}
-
-function validateArgs(a: MemoryRecallArgs): string | null {
-  for (const rel of a.relation_constraints ?? []) {
-    if (isBroadRelation(rel)) {
-      return "memory_recall requires concrete relation_constraints. Broad relations like related_to are not valid for structured lookup.";
-    }
-  }
-  if (a.mode === "typed_neighborhood") {
-    if (!a.candidate_type?.trim()) {
-      return "typed_neighborhood requires candidate_type.";
-    }
-    if ((a.relation_constraints?.length ?? 0) !== 1) {
-      return "typed_neighborhood requires exactly one relation_constraints value.";
-    }
-  }
-  return null;
-}
-
-function isBroadRelation(rel: string): boolean {
-  let r = rel.trim().toLowerCase();
-  r = r.replace(/^\^/, "").replace(/\^-1$/, "");
-  return ["related_to", "relates_to", "associated_with", "about", "mentions", "other"].includes(r);
-}
-
-function coerceArgs(argsJson: string): string {
-  let raw: Record<string, unknown>;
-  try {
-    raw = JSON.parse(argsJson) as Record<string, unknown>;
-  } catch {
-    return argsJson;
-  }
-  let changed = false;
-  for (const field of ["anchor_mentions", "relation_constraints", "scope_filter"]) {
-    const v = raw[field];
-    if (typeof v === "string") {
-      try {
-        raw[field] = JSON.parse(v);
-        changed = true;
-      } catch {
-        /* keep */
-      }
-    }
-  }
-  for (const field of ["result_limit", "evidence_budget"]) {
-    const v = raw[field];
-    if (typeof v === "string") {
-      const n = Number(v);
-      if (!Number.isNaN(n)) {
-        raw[field] = n;
-        changed = true;
-      }
-    }
-  }
-  return changed ? JSON.stringify(raw) : argsJson;
-}
-
-function shapeResult(env: ResponseEnvelope): ToolResult {
-  let quality = "structured";
-  const warnings = envelopeWarnings(env);
-  if (env.reason === "degraded") {
-    quality = "structured_degraded";
-    warnings.unshift({
-      code: "bundle_degraded",
-      message: "memory bundle degraded — results may be incomplete",
-    });
-  }
-  const cands = env.candidates.map((c) => {
-    const m: Record<string, unknown> = {
-      value: c.value,
-      score: c.score,
-      evidence: c.evidence,
-      supporting_event_ids: c.supporting_event_ids,
-    };
-    if (c.scope != null) m.scope = c.scope;
-    if (c.support_count != null) m.support_count = c.support_count;
-    if (c.distinct_session_count != null) {
-      m.distinct_session_count = c.distinct_session_count;
-    }
-    return m;
-  });
-  const out = {
-    source: "memory_sidecar",
-    evidence_quality: quality,
-    bundle_version: env.bundle_version ?? null,
-    memory_block: env.memory_block ?? null,
-    candidates: cands,
-    warnings,
-    fallback_reason: null,
-  };
-  return { content: JSON.stringify(out) };
-}
-
-function permanentResult(env: ResponseEnvelope | null): ToolResult {
-  const out = {
-    source: "memory_sidecar",
-    evidence_quality: "structured",
-    bundle_version: env?.bundle_version ?? null,
-    candidates: [],
-    warnings: envelopeWarnings(env),
-    fallback_reason: null,
-  };
-  return { content: JSON.stringify(out), isError: true };
-}
-
-function envelopeWarnings(env: ResponseEnvelope | null): Record<string, unknown>[] {
-  const out: Record<string, unknown>[] = [];
-  if (!env) return out;
-  for (const w of env.warnings ?? []) {
-    out.push({ code: w.code, message: w.message });
-  }
-  if (env.error) {
-    out.push({
-      code: env.error.code,
-      message: env.error.message,
-      sub_code: env.error.details?.sub_code,
-    });
-  }
-  return out;
-}
-
-function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(new Error("aborted"));
-      return;
-    }
-    const t = setTimeout(resolve, ms);
-    signal?.addEventListener("abort", () => {
-      clearTimeout(t);
-      reject(new Error("aborted"));
-    }, { once: true });
-  });
-}
-
-/** @deprecated Use createFallbackQuery — kept for backward-compatible imports. */
-export function createStubFallback(
-  memoryMdPaths: string[],
-  sessionsDir = "",
-): FallbackQuery {
-  return createFallbackQuery({ sessionsDir, memoryMdPaths });
-}
-
-export { createFallbackQuery };
-
-export function createMemoryRecallTool(
-  service: MemoryQuerier,
-  fallback: FallbackQuery | null,
-  rerankOpts?: RerankOptions | null,
-): MemoryRecallTool {
-  return new MemoryRecallTool(service, fallback, rerankOpts ?? null);
-}