@chendpoc/pi-memory 0.1.12 → 0.2.0

package/src/preflight/hook.ts

@@ -1,199 +0,0 @@
-import type { RerankOptions } from "../fallback/llmRerank.js";
-import type { MemoryConfig } from "../config.js";
-import type { FallbackQuery } from "../types.js";
-import type { MemoryService } from "../service.js";
-import type { QueryIntent } from "../types.js";
-import {
-  detectMemoryIntents,
-  type DetectIntentsOptions,
-  type MemoryHelperLLM,
-} from "./detectIntents.js";
-import { renderFallbackPrivateMemory, renderPrivateMemoryContext, type PreflightQueryResult } from "./render.js";
-import { injectPrivateMemoryContext } from "./strip.js";
-import {
-  deleteNegativeCache,
-  isNegativeCached,
-  setNegativeCache,
-} from "../cache/memoryCaches.js";
-
-export type { MemoryHelperLLM };
-
-export const MEMORY_PREFLIGHT_QUERY_TIMEOUT_MS = 2_000;
-
-export interface MemoryPreflightOptions extends DetectIntentsOptions {
-  helper?: MemoryHelperLLM | null;
-  /** When true, run helper even if lexical gate would skip. */
-  forceHelper?: boolean;
-  /** Fallback query for degraded path when sidecar is not ready. */
-  fallback?: FallbackQuery | null;
-  /** LLM rerank options for fallback search results. */
-  rerankOpts?: RerankOptions | null;
-  /**
-   * Optional progress callback emitted at key stages (intent detection,
-   * graph query, FTS search, rerank). Wire to ctx.ui.setWorkingMessage for
-   * visible feedback during slow sidecar queries.
-   */
-  onProgress?: (message: string) => void;
-  /**
-   * When the graph is ready but returns no usable results, cascade to a
-   * semantic fallback: broader FTS recall + single LLM rerank.
-   * Requires both `fallback` and `rerankOpts` to be set.
-   * Defaults to true — set to false to disable the cascade.
-   */
-  semanticFallback?: boolean;
-}
-
-export interface MemoryPreflightResult {
-  /** Full injected user text (scaffold + private memory + payload), or undefined. */
-  injectedText?: string;
-  /** Raw <private_memory> block when context was returned. */
-  privateContext?: string;
-}
-
-export interface BeforeTurnInput {
-  /** Scaffolded user message text sent to the model (may include date/CWD scaffolding). */
-  scaffoldedText: string;
-  /** Raw user payload without scaffolding — used for intent detection. */
-  userPayload: string;
-  /** First message in conversation — enables forceHelper gate. */
-  isFirstTurn?: boolean;
-  /** Set when preflight injected context (not for persistence). */
-  privateContext?: string;
-  signal?: AbortSignal;
-}
-
-export type BeforeTurnHook = (input: BeforeTurnInput) => Promise<BeforeTurnInput>;
-
-/**
- * Fail-silent implicit episodic preflight: detect intents → batch query → inject
- * <private_memory> into the in-flight user message. Never throws.
- */
-export async function runMemoryPreflight(
-  query: string,
-  service: MemoryService,
-  options: MemoryPreflightOptions = {},
-): Promise<MemoryPreflightResult | null> {
-  if (isNegativeCached(query)) return null;
-
-  try {
-    if (service.status() !== "ready") {
-      if (!options.fallback) {
-        setNegativeCache(query);
-        return null;
-      }
-      options.onProgress?.("Searching session history…");
-      const privateContext = await renderFallbackPrivateMemory(query, options.fallback, {
-        rerankOpts: options.rerankOpts,
-        onProgress: options.onProgress,
-      });
-      if (!privateContext.trim()) {
-        setNegativeCache(query);
-        return null;
-      }
-      deleteNegativeCache(query);
-      return { privateContext };
-    }
-
-    options.onProgress?.("Detecting memory intents…");
-    const intents = await detectMemoryIntents(query, options.helper ?? null, {
-      forceHelper: options.forceHelper,
-      signal: options.signal,
-    });
-    if (intents.length === 0) {
-      setNegativeCache(query);
-      return null;
-    }
-
-    if (service.getStatus().mode === "sidecar") {
-      options.onProgress?.("Querying memory graph…");
-    }
-
-    const timeout = AbortSignal.timeout(MEMORY_PREFLIGHT_QUERY_TIMEOUT_MS);
-    const combined = options.signal
-      ? AbortSignal.any([options.signal, timeout])
-      : timeout;
-
-    const results = await service.queryBatch(intents, combined);
-    if (timeout.aborted) {
-      setNegativeCache(query);
-      return null;
-    }
-
-    const renderInput: PreflightQueryResult[] = results.map((r) => ({
-      envelope: r.envelope,
-      ok: r.errorClass === "ok" && r.envelope != null && !r.envelope.error,
-    }));
-
-    const privateContext = renderPrivateMemoryContext(intents, renderInput);
-    if (!privateContext.trim()) {
-      // Graph was ready but returned no usable results.
-      // Cascade to semantic fallback (broader FTS + single LLM rerank) when
-      // both a fallback store and a rerank client are available.
-      if (
-        options.semanticFallback !== false &&
-        options.fallback &&
-        options.rerankOpts
-      ) {
-        options.onProgress?.("Searching session history…");
-        const semanticCtx = await renderFallbackPrivateMemory(query, options.fallback, {
-          rerankOpts: options.rerankOpts,
-          onProgress: options.onProgress,
-        });
-        if (semanticCtx.trim()) {
-          deleteNegativeCache(query);
-          return { privateContext: semanticCtx };
-        }
-      }
-      setNegativeCache(query);
-      return null;
-    }
-
-    deleteNegativeCache(query);
-    return { privateContext };
-  } catch {
-    setNegativeCache(query);
-    return null;
-  }
-}
-
-/**
- * Pi beforeTurn hook factory — wire into pi-coding-agent turn lifecycle.
- *
- * ```ts
- * const hook = createBeforeTurnHook(service, config, { helper: mySmallModel });
- * api.onBeforeTurn?.(hook);
- * ```
- *
- * On persist/summary, call `stripPrivateMemory` on user message text so recalled
- * facts are not written to session history.
- */
-export function createBeforeTurnHook(
-  service: MemoryService,
-  config: MemoryConfig,
-  options: { helper?: MemoryHelperLLM | null; fallback?: FallbackQuery | null } = {},
-): BeforeTurnHook {
-  const fallback = options.fallback ?? null;
-  return async (input: BeforeTurnInput): Promise<BeforeTurnInput> => {
-    const preflight = await runMemoryPreflight(input.userPayload, service, {
-      helper: options.helper ?? null,
-      forceHelper: input.isFirstTurn ?? false,
-      signal: input.signal,
-      fallback,
-    });
-    if (!preflight?.privateContext) return input;
-
-    const injectedText = injectPrivateMemoryContext(
-      input.scaffoldedText,
-      input.userPayload,
-      preflight.privateContext,
-    );
-    return {
-      ...input,
-      scaffoldedText: injectedText,
-      privateContext: preflight.privateContext,
-    };
-  };
-}
-
-/** @internal exported for tests */
-export type { QueryIntent };

package/src/service.ts

@@ -1,306 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import type { MemoryConfig } from "./config.js";
-import { invalidateMemoryCaches } from "./cache/memoryCaches.js";
-import { LocalGraphQuerier } from "./local/graphQuery.js";
-import { currentBundleReadable } from "./sidecar/bundle.js";
-import { SidecarClient } from "./sidecar/client.js";
-import { SidecarProcess } from "./sidecar/process.js";
-import { openSessionIndex, type SessionIndex } from "./fallback/sessionIndex.js";
-import { createTrainScheduler, type TrainScheduler, type SchedulerLog } from "./trainer/scheduler.js";
-import type { ErrorClass } from "./errclass.js";
-import type {
-  HealthPayload,
-  QueryIntent,
-  ResponseEnvelope,
-  ServiceStatus,
-} from "./types.js";
-
-export interface MemoryServiceStatus {
-  status: ServiceStatus;
-  reason?: string;
-  mode?: "sidecar" | "local_graph";
-  health?: HealthPayload | null;
-}
-
-export interface QueryBatchResult {
-  envelope: ResponseEnvelope | null;
-  errorClass: ErrorClass;
-  transportError?: Error;
-}
-
-/**
- * Local memory service with two query backends:
- * 1. tlm sidecar (Unix socket) — when tlm binary is available
- * 2. LocalGraphQuerier — direct graph.json query when tlm is missing
- *
- * Both require a bundle at bundleRoot/current.
- */
-export class MemoryService {
-  private serviceStatus: ServiceStatus = "disabled";
-  private reason = "";
-  private mode: "sidecar" | "local_graph" | null = null;
-  private process: SidecarProcess | null = null;
-  private client: SidecarClient | null = null;
-  private localQuerier: LocalGraphQuerier | null = null;
-  private abort: AbortController | null = null;
-  private scheduler: TrainScheduler | null = null;
-  private sessionIndex: SessionIndex | null = null;
-  private bundleMtimes: { graph: number; manifest: number } | null = null;
-  private lastBundleCheckMs = 0;
-  private static readonly BUNDLE_CHECK_INTERVAL_MS = 5_000;
-
-  constructor(private cfg: MemoryConfig) {}
-
-  getConfig(): MemoryConfig {
-    return this.cfg;
-  }
-
-  status(): ServiceStatus {
-    return this.serviceStatus;
-  }
-
-  getStatus(): MemoryServiceStatus {
-    return {
-      status: this.serviceStatus,
-      reason: this.reason || undefined,
-      mode: this.mode ?? undefined,
-    };
-  }
-
-  getClient(): SidecarClient | null {
-    return this.client;
-  }
-
-  async start(): Promise<void> {
-    if (this.cfg.provider === "disabled") {
-      this.serviceStatus = "disabled";
-      return;
-    }
-
-    if (this.cfg.provider !== "local") {
-      this.serviceStatus = "unavailable";
-      this.reason = "cloud_mode_not_implemented_in_pi_memory_v0.1";
-      return;
-    }
-
-    if (!currentBundleReadable(this.cfg.bundleRoot)) {
-      this.serviceStatus = "unavailable";
-      this.reason = "bundle_missing";
-      return;
-    }
-
-    this.serviceStatus = "initializing";
-    this.abort = new AbortController();
-
-    if (await this.trySidecar()) return;
-
-    if (this.tryLocalGraph()) return;
-
-    this.serviceStatus = "unavailable";
-    this.reason = "no_query_backend";
-  }
-
-  private async trySidecar(): Promise<boolean> {
-    this.process = new SidecarProcess(this.cfg);
-    try {
-      await this.process.resolveBinary();
-    } catch {
-      this.process = null;
-      return false;
-    }
-
-    try {
-      await this.process.spawn();
-      await this.process.waitReady(this.abort!.signal);
-      this.client = this.process.getClient();
-      this.serviceStatus = "ready";
-      this.mode = "sidecar";
-      this.reason = "";
-      return true;
-    } catch {
-      await this.process.stop();
-      this.process = null;
-      this.client = null;
-      return false;
-    }
-  }
-
-  private tryLocalGraph(): boolean {
-    const querier = new LocalGraphQuerier(this.cfg.bundleRoot);
-    if (!querier.load()) return false;
-    this.localQuerier = querier;
-    this.serviceStatus = "ready";
-    this.mode = "local_graph";
-    this.reason = "";
-    return true;
-  }
-
-  startAutoTrainer(logger?: (log: SchedulerLog) => void): void {
-    this.scheduler?.stop();
-    this.scheduler = createTrainScheduler(
-      {
-        interval: this.cfg.trainer.auto_interval,
-        trainConfig: {
-          sessionsDir: this.cfg.sessionsDir,
-          bundleRoot: this.cfg.bundleRoot,
-        },
-        onSuccess: () => { void this.notifyBundleUpdated(); },
-      },
-      logger,
-    );
-  }
-
-  /**
-   * Check if the on-disk bundle has changed and hot-reload if needed.
-   * Debounced to at most once per BUNDLE_CHECK_INTERVAL_MS to avoid excess stat calls.
-   * For local_graph, reloads LocalGraphQuerier in-process.
-   * For sidecar, issues a /bundle/reload request.
-   * Invalidates all memory caches on successful reload.
-   */
-  async ensureFreshBundle(): Promise<void> {
-    if (this.serviceStatus !== "ready") return;
-    const now = Date.now();
-    if (now - this.lastBundleCheckMs < MemoryService.BUNDLE_CHECK_INTERVAL_MS) return;
-    this.lastBundleCheckMs = now;
-
-    if (this.mode === "local_graph" && this.localQuerier) {
-      const reloaded = this.localQuerier.reloadIfStale();
-      if (reloaded) invalidateMemoryCaches();
-      return;
-    }
-
-    if (this.mode === "sidecar" && this.client) {
-      const graphPath = path.join(this.cfg.bundleRoot, "current", "graph.json");
-      const manifestPath = path.join(this.cfg.bundleRoot, "current", "manifest.json");
-      try {
-        const graphMtime = fs.statSync(graphPath).mtimeMs;
-        const manifestMtime = fs.statSync(manifestPath).mtimeMs;
-        if (!this.bundleMtimes) {
-          this.bundleMtimes = { graph: graphMtime, manifest: manifestMtime };
-          return;
-        }
-        const changed =
-          graphMtime !== this.bundleMtimes.graph ||
-          manifestMtime !== this.bundleMtimes.manifest;
-        if (!changed) return;
-        this.bundleMtimes = { graph: graphMtime, manifest: manifestMtime };
-        await this.client.reload();
-        invalidateMemoryCaches();
-      } catch {
-        /* stat or reload failure — continue with current bundle */
-      }
-    }
-  }
-
-  /**
-   * Force an immediate bundle freshness check (bypasses the debounce).
-   * Called by the auto-trainer scheduler after a successful train run.
-   */
-  async notifyBundleUpdated(): Promise<void> {
-    this.lastBundleCheckMs = 0;
-    await this.ensureFreshBundle();
-  }
-
-  startSessionIndex(): void {
-    const dbDir = this.cfg.bundleRoot;
-    try {
-      fs.mkdirSync(dbDir, { recursive: true });
-    } catch {
-      return;
-    }
-    const dbPath = path.join(dbDir, "sessions.db");
-    const idx = openSessionIndex(dbPath);
-    if (!idx) return;
-    this.sessionIndex = idx;
-    void idx.incrementalIndex(this.cfg.sessionsDir).catch(() => {});
-  }
-
-  getSessionIndex(): SessionIndex | null {
-    return this.sessionIndex;
-  }
-
-  async stop(): Promise<void> {
-    this.abort?.abort();
-    this.scheduler?.stop();
-    this.scheduler = null;
-    this.sessionIndex?.close();
-    this.sessionIndex = null;
-    await this.process?.stop();
-    this.process = null;
-    this.client = null;
-    this.localQuerier = null;
-    this.mode = null;
-    if (this.cfg.provider === "disabled") {
-      this.serviceStatus = "disabled";
-    } else {
-      this.serviceStatus = "unavailable";
-      this.reason = "stopped";
-    }
-  }
-
-  async queryBatch(
-    intents: QueryIntent[],
-    signal?: AbortSignal,
-  ): Promise<QueryBatchResult[]> {
-    if (intents.length === 0) return [];
-    return Promise.all(
-      intents.map(async (intent) => {
-        const r = await this.query(intent, signal);
-        return {
-          envelope: r.env,
-          errorClass: r.errorClass,
-          transportError: r.transportError,
-        };
-      }),
-    );
-  }
-
-  async query(
-    intent: QueryIntent,
-    signal?: AbortSignal,
-  ): Promise<{
-    env: ResponseEnvelope | null;
-    errorClass: ErrorClass;
-    transportError?: Error;
-  }> {
-    if (this.serviceStatus !== "ready") {
-      return { env: null, errorClass: "unavailable" };
-    }
-    await this.ensureFreshBundle();
-
-    if (this.client && this.mode === "sidecar") {
-      const timeout = AbortSignal.timeout(this.cfg.queryTimeoutMs);
-      const combined = signal
-        ? AbortSignal.any([signal, timeout])
-        : timeout;
-      return this.client.query(intent, combined);
-    }
-
-    if (this.localQuerier && this.mode === "local_graph") {
-      return this.localQuerier.query(intent);
-    }
-
-    return { env: null, errorClass: "unavailable" };
-  }
-
-  async health(): Promise<HealthPayload | null> {
-    if (this.client) {
-      try {
-        return await this.client.health();
-      } catch {
-        return null;
-      }
-    }
-    if (this.localQuerier) {
-      return {
-        ready: true,
-        compatibility: "local_graph",
-        protocol_version: 1,
-        uptime_secs: 0,
-        status_message: `local graph query (${this.localQuerier.isLoaded() ? "loaded" : "not loaded"})`,
-      };
-    }
-    return null;
-  }
-}

package/src/settings.ts

@@ -1,126 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-
-import {
-  defaultMemoryConfig,
-  normalizeMemoryConfig,
-  type ExtractorType,
-  type MemoryConfig,
-  type MemoryProvider,
-  type TrainerConfig,
-} from "./config.js";
-import type { OllamaConfig } from "./adapters/ollamaClient.js";
-import type { OpenAICompatConfig } from "./adapters/openaiCompatClient.js";
-
-export interface MemorySettingsFile {
-  provider?: MemoryProvider;
-  tlmPath?: string;
-  socketPath?: string;
-  bundleRoot?: string;
-  sidecarReadyTimeoutMs?: number;
-  queryTimeoutMs?: number;
-  clientRequestTimeoutMs?: number;
-  sessionsDir?: string;
-  memoryMdPaths?: string[];
-  /** LLM for intent detection, rerank, and LLM extraction. Overrides default helper model. */
-  helperModel?: string;
-  /** Ollama local API config for helper / trainer / rerank. */
-  ollama?: Partial<OllamaConfig>;
-  /** OpenAI-compatible endpoint config (vLLM, SGLang, LM Studio, etc.) */
-  vllm?: Partial<OpenAICompatConfig>;
-  trainer?: Partial<TrainerConfig>;
-}
-
-export interface LoadedMemorySettings {
-  config: MemoryConfig;
-  helperModel: string | undefined;
-  ollama: OllamaConfig | null;
-  vllm: OpenAICompatConfig | null;
-  configPath: string;
-}
-
-/** Default path: ~/.pi/agent/memory.json */
-export function defaultMemoryConfigPath(): string {
-  return path.join(getAgentDir(), "memory.json");
-}
-
-function readMemorySettingsFile(configPath = defaultMemoryConfigPath()): MemorySettingsFile {
-  try {
-    const raw = fs.readFileSync(configPath, "utf8");
-    const parsed = JSON.parse(raw) as unknown;
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return {};
-    }
-    return parsed as MemorySettingsFile;
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-      return {};
-    }
-    throw new Error(
-      `Failed to load pi-memory config from ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-}
-
-/** Load pi-memory config from ~/.pi/agent/memory.json. */
-export function loadMemorySettings(
-  overrides: Partial<MemoryConfig> = {},
-  configPath = defaultMemoryConfigPath(),
-): LoadedMemorySettings {
-  const fileSettings = readMemorySettingsFile(configPath);
-  const { helperModel, ollama, vllm, trainer, ...configFields } = fileSettings;
-
-  const config = normalizeMemoryConfig({
-    ...configFields,
-    ...(trainer ? { trainer } : {}),
-    ...overrides,
-  } as Partial<MemoryConfig> & Record<string, unknown>);
-
-  let resolvedOllama: OllamaConfig | null = null;
-  if (ollama && ollama.model) {
-    resolvedOllama = {
-      baseUrl: ollama.baseUrl?.trim() || "http://localhost:11434",
-      model: ollama.model.trim(),
-    };
-  }
-
-  let resolvedVllm: OpenAICompatConfig | null = null;
-  if (vllm && vllm.model) {
-    resolvedVllm = {
-      baseUrl: vllm.baseUrl?.trim() || "http://localhost:8000",
-      model: vllm.model.trim(),
-      apiKey: vllm.apiKey?.trim() || undefined,
-    };
-  }
-
-  return {
-    config,
-    helperModel: helperModel?.trim() || undefined,
-    ollama: resolvedOllama,
-    vllm: resolvedVllm,
-    configPath,
-  };
-}
-
-/** Convenience alias when only MemoryConfig is needed. */
-export function loadMemoryConfig(
-  overrides: Partial<MemoryConfig> = {},
-  configPath = defaultMemoryConfigPath(),
-): MemoryConfig {
-  return loadMemorySettings(overrides, configPath).config;
-}
-
-export function resolveHelperModelSpec(
-  flagValue: string | boolean | undefined,
-  settingsHelperModel: string | undefined,
-): string | undefined {
-  if (typeof flagValue === "string" && flagValue.trim()) {
-    return flagValue.trim();
-  }
-  return settingsHelperModel;
-}
-
-export { defaultMemoryConfig };
-export type { ExtractorType, MemoryProvider, TrainerConfig };

package/src/sidecar/bundle.ts

@@ -1,52 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-/**
- * True when `<bundleRoot>/current` resolves to a directory containing
- * JSON-parseable manifest.json (Kocoro memory/service.go currentBundleReadable).
- */
-export function currentBundleReadable(bundleRoot: string): boolean {
-  const currentPath = path.join(bundleRoot, "current");
-  let st: fs.Stats;
-  try {
-    st = fs.statSync(currentPath);
-  } catch {
-    return false;
-  }
-  if (!st.isDirectory()) return false;
-  try {
-    const data = fs.readFileSync(path.join(currentPath, "manifest.json"), "utf8");
-    JSON.parse(data);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export interface BundleManifestFile {
-  path: string;
-  size: number;
-  sha256: string;
-}
-
-export interface BundleManifest {
-  bundle_ts: string;
-  bundle_version: string;
-  size_bytes: number;
-  integrity_sha256: string;
-  files: BundleManifestFile[];
-}
-
-export function readCurrentManifest(bundleRoot: string): BundleManifest | null {
-  if (!currentBundleReadable(bundleRoot)) return null;
-  const currentPath = path.join(bundleRoot, "current");
-  try {
-    const raw = fs.readFileSync(
-      path.join(currentPath, "manifest.json"),
-      "utf8",
-    );
-    return JSON.parse(raw) as BundleManifest;
-  } catch {
-    return null;
-  }
-}