@chendpoc/pi-memory 0.1.0

package/dist/sidecar/client.js

@@ -0,0 +1,107 @@
+import { randomBytes } from "node:crypto";
+import http from "node:http";
+import { classifyHTTP, classifyTransportError, ErrTransport, } from "../errclass.js";
+function requestId() {
+    return `req-${randomBytes(6).toString("hex")}`;
+}
+export class SidecarClient {
+    socketPath;
+    timeoutMs;
+    constructor(socketPath, timeoutMs) {
+        this.socketPath = socketPath;
+        this.timeoutMs = timeoutMs;
+    }
+    async health(signal) {
+        return this.do("GET", "/health", undefined, signal);
+    }
+    async query(intent, signal) {
+        const rid = requestId();
+        const body = { intent, request_id: rid };
+        try {
+            const { status, data } = await this.doRaw("POST", "/query", body, signal, rid);
+            return {
+                env: data,
+                errorClass: classifyHTTP(status, data),
+            };
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes("transport")) {
+                return {
+                    env: null,
+                    errorClass: classifyTransportError(err),
+                    transportError: err,
+                };
+            }
+            return {
+                env: null,
+                errorClass: "unavailable",
+                transportError: err instanceof Error ? err : new Error(String(err)),
+            };
+        }
+    }
+    async reload(signal) {
+        return this.do("POST", "/bundle/reload", {}, signal);
+    }
+    async do(method, path, body, signal, requestIdHeader) {
+        const { data } = await this.doRaw(method, path, body, signal, requestIdHeader);
+        return data;
+    }
+    doRaw(method, path, body, signal, requestIdHeader) {
+        return new Promise((resolve, reject) => {
+            const payload = body != null ? JSON.stringify(body) : undefined;
+            const req = http.request({
+                socketPath: this.socketPath,
+                path,
+                method,
+                headers: {
+                    "X-Request-ID": requestIdHeader ?? requestId(),
+                    ...(payload
+                        ? {
+                            "Content-Type": "application/json",
+                            "Content-Length": Buffer.byteLength(payload),
+                        }
+                        : {}),
+                },
+                timeout: this.timeoutMs,
+            }, (res) => {
+                const chunks = [];
+                res.on("data", (c) => chunks.push(c));
+                res.on("end", () => {
+                    const text = Buffer.concat(chunks).toString("utf8");
+                    if (!text) {
+                        reject(new Error(`${ErrTransport.message}: empty body`));
+                        return;
+                    }
+                    try {
+                        resolve({
+                            status: res.statusCode ?? 0,
+                            data: JSON.parse(text),
+                        });
+                    }
+                    catch (e) {
+                        reject(new Error(`${ErrTransport.message}: decode: ${e instanceof Error ? e.message : e}`));
+                    }
+                });
+            });
+            req.on("timeout", () => {
+                req.destroy(new Error(`${ErrTransport.message}: timeout`));
+            });
+            req.on("error", (err) => {
+                reject(new Error(`${ErrTransport.message}: ${err.message}`));
+            });
+            if (signal) {
+                if (signal.aborted) {
+                    req.destroy(new Error(`${ErrTransport.message}: aborted`));
+                    return;
+                }
+                signal.addEventListener("abort", () => {
+                    req.destroy(new Error(`${ErrTransport.message}: aborted`));
+                }, { once: true });
+            }
+            if (payload)
+                req.write(payload);
+            req.end();
+        });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/sidecar/client.js.map

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

package/dist/sidecar/process.d.ts

@@ -0,0 +1,14 @@
+import type { MemoryConfig } from "../config.js";
+import { SidecarClient } from "./client.js";
+export declare class SidecarProcess {
+    private readonly cfg;
+    private child;
+    private readonly client;
+    constructor(cfg: MemoryConfig);
+    getClient(): SidecarClient;
+    resolveBinary(): Promise<string>;
+    spawn(): Promise<void>;
+    waitReady(signal?: AbortSignal): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=process.d.ts.map

package/dist/sidecar/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/sidecar/process.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,qBAAa,cAAc;IAIb,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHhC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAEV,GAAG,EAAE,YAAY;IAO9C,SAAS,IAAI,aAAa;IAIpB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAUhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiCtB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC9C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA2B5B"}

package/dist/sidecar/process.js

@@ -0,0 +1,126 @@
+import { access, constants } from "node:fs/promises";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { SidecarClient } from "./client.js";
+export class SidecarProcess {
+    cfg;
+    child = null;
+    client;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.client = new SidecarClient(cfg.socketPath, Math.min(cfg.clientRequestTimeoutMs, 5_000));
+    }
+    getClient() {
+        return this.client;
+    }
+    async resolveBinary() {
+        const bin = this.cfg.tlmPath;
+        if (path.isAbsolute(bin)) {
+            await access(bin, constants.X_OK);
+            return bin;
+        }
+        // PATH lookup: spawn with shell on unix
+        return bin;
+    }
+    async spawn() {
+        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", (err) => {
+            console.error("[pi-memory] sidecar spawn error:", err.message);
+        });
+        this.child.unref?.();
+    }
+    async waitReady(signal) {
+        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() {
+        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((resolve) => {
+            const t = setTimeout(resolve, 2_000);
+            child.on("exit", () => {
+                clearTimeout(t);
+                resolve();
+            });
+        });
+    }
+}
+function sleep(ms, signal) {
+    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 });
+    });
+}
+//# sourceMappingURL=process.js.map

package/dist/sidecar/process.js.map

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

package/dist/tools/memoryAppend.d.ts

@@ -0,0 +1,37 @@
+import type { ToolResult } from "../types.js";
+export declare const MEMORY_APPEND_NAME = "memory_append";
+export declare const MEMORY_APPEND_DESCRIPTION: string;
+export declare const MEMORY_APPEND_PROMPT_SNIPPET = "Append durable notes to MEMORY.md";
+export declare const MEMORY_APPEND_PROMPT_GUIDELINES: readonly ["Use memory_append to persist user preferences or facts the user explicitly asked to remember — not for transient task state."];
+export declare const MEMORY_APPEND_PARAMETERS: {
+    readonly type: "object";
+    readonly properties: {
+        readonly content: {
+            readonly type: "string";
+            readonly description: "New entries to append (markdown bullet points). Write in English by default.";
+        };
+    };
+    readonly required: readonly ["content"];
+};
+export declare function appendToMemoryMd(memoryMdPath: string, content: string): Promise<void>;
+export declare class MemoryAppendTool {
+    private readonly memoryMdPath;
+    constructor(memoryMdPath: string);
+    info(): {
+        name: string;
+        description: string;
+        parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly content: {
+                    readonly type: "string";
+                    readonly description: "New entries to append (markdown bullet points). Write in English by default.";
+                };
+            };
+            readonly required: readonly ["content"];
+        };
+    };
+    run(argsJson: string): Promise<ToolResult>;
+}
+export declare function createMemoryAppendTool(memoryMdPath: string): MemoryAppendTool;
+//# sourceMappingURL=memoryAppend.d.ts.map

package/dist/tools/memoryAppend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryAppend.d.ts","sourceRoot":"","sources":["../../src/tools/memoryAppend.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD,eAAO,MAAM,yBAAyB,QAEoC,CAAC;AAE3E,eAAO,MAAM,4BAA4B,sCAAsC,CAAC;AAEhF,eAAO,MAAM,+BAA+B,2IAElC,CAAC;AAEX,eAAO,MAAM,wBAAwB;;;;;;;;;CAU3B,CAAC;AA6BX,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAWf;AAED,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,MAAM;IAEjD,IAAI;;;;;;;;;;;;;;IAQE,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAwBjD;AAED,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,gBAAgB,CAE7E"}

package/dist/tools/memoryAppend.js

@@ -0,0 +1,99 @@
+import fs from "node:fs/promises";
+import { open } from "node:fs/promises";
+import path from "node:path";
+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.",
+];
+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"],
+};
+const LOCK_RETRIES = 50;
+const LOCK_DELAY_MS = 20;
+async function withAppendLock(lockPath, fn) {
+    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, content) {
+    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 {
+    memoryMdPath;
+    constructor(memoryMdPath) {
+        this.memoryMdPath = memoryMdPath;
+    }
+    info() {
+        return {
+            name: MEMORY_APPEND_NAME,
+            description: MEMORY_APPEND_DESCRIPTION,
+            parameters: MEMORY_APPEND_PARAMETERS,
+        };
+    }
+    async run(argsJson) {
+        let raw;
+        try {
+            raw = JSON.parse(argsJson);
+        }
+        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) {
+    return new MemoryAppendTool(memoryMdPath);
+}
+//# sourceMappingURL=memoryAppend.js.map

package/dist/tools/memoryAppend.js.map

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

package/dist/tools/memoryRecall.d.ts

@@ -0,0 +1,113 @@
+import { createFallbackQuery } from "../fallback/index.js";
+import { type RerankOptions } from "../fallback/llmRerank.js";
+import type { FallbackQuery, MemoryQuerier, QueryIntent, ToolResult } from "../types.js";
+export declare const MEMORY_RECALL_NAME = "memory_recall";
+export declare const MEMORY_RECALL_DESCRIPTION: string;
+export declare const MEMORY_RECALL_PROMPT_SNIPPET = "Query local episodic memory by entity or relationship";
+export declare const MEMORY_RECALL_PROMPT_GUIDELINES: readonly ["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."];
+export declare const MEMORY_RECALL_PARAMETERS: {
+    readonly type: "object";
+    readonly properties: {
+        readonly mode: {
+            readonly type: "string";
+            readonly enum: readonly ["direct_relation", "path_query", "typed_neighborhood"];
+        };
+        readonly anchor_mentions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly relation_constraints: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly candidate_type: {
+            readonly type: "string";
+        };
+        readonly scope_filter: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly target_slot: {
+            readonly type: "string";
+            readonly enum: readonly ["head", "tail"];
+        };
+        readonly time_window: {
+            readonly type: "string";
+        };
+        readonly evidence_budget: {
+            readonly type: "integer";
+        };
+        readonly result_limit: {
+            readonly type: "integer";
+        };
+    };
+    readonly required: readonly ["anchor_mentions"];
+};
+export declare class MemoryRecallTool {
+    private readonly service;
+    private readonly fallback;
+    private readonly rerankOpts;
+    constructor(service: MemoryQuerier, fallback?: FallbackQuery | null, rerankOpts?: RerankOptions | null);
+    info(): {
+        name: string;
+        description: string;
+        parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly mode: {
+                    readonly type: "string";
+                    readonly enum: readonly ["direct_relation", "path_query", "typed_neighborhood"];
+                };
+                readonly anchor_mentions: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly relation_constraints: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly candidate_type: {
+                    readonly type: "string";
+                };
+                readonly scope_filter: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly target_slot: {
+                    readonly type: "string";
+                    readonly enum: readonly ["head", "tail"];
+                };
+                readonly time_window: {
+                    readonly type: "string";
+                };
+                readonly evidence_budget: {
+                    readonly type: "integer";
+                };
+                readonly result_limit: {
+                    readonly type: "integer";
+                };
+            };
+            readonly required: readonly ["anchor_mentions"];
+        };
+    };
+    run(argsJson: string, signal?: AbortSignal): Promise<ToolResult>;
+    runIntent(intent: QueryIntent, signal?: AbortSignal): Promise<ToolResult>;
+    private fallbackResult;
+}
+/** @deprecated Use createFallbackQuery — kept for backward-compatible imports. */
+export declare function createStubFallback(memoryMdPaths: string[], sessionsDir?: string): FallbackQuery;
+export { createFallbackQuery };
+export declare function createMemoryRecallTool(service: MemoryQuerier, fallback: FallbackQuery | null, rerankOpts?: RerankOptions | null): MemoryRecallTool;
+//# sourceMappingURL=memoryRecall.d.ts.map

package/dist/tools/memoryRecall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryRecall.d.ts","sourceRoot":"","sources":["../../src/tools/memoryRecall.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAiB,KAAK,aAAa,EAAqB,MAAM,0BAA0B,CAAC;AAEhG,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAoB,WAAW,EAA+B,UAAU,EAAE,MAAM,aAAa,CAAC;AAExI,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD,eAAO,MAAM,yBAAyB,QAM8E,CAAC;AAErH,eAAO,MAAM,4BAA4B,0DACgB,CAAC;AAE1D,eAAO,MAAM,+BAA+B,yPAGlC,CAAC;AAEX,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiB3B,CAAC;AAEX,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAFV,OAAO,EAAE,aAAa,EACtB,QAAQ,GAAE,aAAa,GAAG,IAAW,EACrC,UAAU,GAAE,aAAa,GAAG,IAAW;IAG1D,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAQE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAehE,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;YA6BjE,cAAc;CAmF7B;AAmKD,kFAAkF;AAClF,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EAAE,EACvB,WAAW,SAAK,GACf,aAAa,CAEf;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAE/B,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,aAAa,GAAG,IAAI,EAC9B,UAAU,CAAC,EAAE,aAAa,GAAG,IAAI,GAChC,gBAAgB,CAElB"}