@remnic/core 1.1.11 → 1.1.13

package/src/peers/types.ts

@@ -0,0 +1,138 @@
+/**
+ * Peer registry types — issue #679 PR 1/5.
+ *
+ * Generalizes the singular identity-anchor model to a multi-peer registry.
+ * Every party Remnic interacts with — humans, agents, integrations, and
+ * "self" — is represented as a `Peer` with an evolving cognitive profile.
+ *
+ * This module defines pure types only. Storage primitives live in
+ * `./storage.ts`. Reasoner integration, recall injection, CLI/HTTP/MCP
+ * surfaces, and migration of existing identity-anchor data ship in later
+ * PRs (2/5 — 5/5).
+ */
+
+/**
+ * Kind of peer.
+ *
+ * - `self`     — the current Remnic operator (replaces singular identity-anchor).
+ * - `human`    — another human collaborator distinct from self.
+ * - `agent`    — another AI agent (Claude Code, Codex, Hermes, etc.).
+ * - `integration` — non-conversational integration (cron, webhook, importer).
+ */
+export type PeerKind = "self" | "human" | "agent" | "integration";
+
+/**
+ * Stable, slow-changing facts about a peer.
+ *
+ * `id` matches `^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$`, 1-64 chars,
+ * with no leading/trailing/consecutive dots or dashes. Stored on disk under
+ * `peers/{id}/identity.md` as YAML frontmatter + markdown body.
+ */
+export interface Peer {
+  /** Stable, opaque identifier. See PEER_ID_PATTERN. */
+  readonly id: string;
+  /** Kind of peer. Drives default profile schema and recall posture. */
+  readonly kind: PeerKind;
+  /** Human-readable display name. Distinct from `id`; mutable. */
+  readonly displayName: string;
+  /** ISO-8601 timestamp of first registration. */
+  readonly createdAt: string;
+  /** ISO-8601 timestamp of most recent update to identity. */
+  readonly updatedAt: string;
+  /** Optional free-form markdown body for the identity kernel. */
+  readonly notes?: string;
+}
+
+/**
+ * Evolving cognitive profile for a peer.
+ *
+ * Updated by the async profile reasoner (PR 2/5) from observable session
+ * signals. Every field carries provenance back to its originating session
+ * and signal. This PR only defines the shape — population is deferred.
+ */
+export interface PeerProfile {
+  /** Peer this profile belongs to. */
+  readonly peerId: string;
+  /** ISO-8601 timestamp of most recent profile mutation. */
+  readonly updatedAt: string;
+  /**
+   * Arbitrary key/value profile fields. Values are markdown strings.
+   * Keys are stable section identifiers (e.g. `communication_style`,
+   * `recurring_concerns`). The reasoner is responsible for choosing
+   * keys; this PR does not constrain them beyond requiring strings.
+   */
+  readonly fields: Record<string, string>;
+  /**
+   * Per-field provenance. Maps field key → list of provenance entries.
+   * A field may have multiple sources (the reasoner accumulates evidence
+   * across sessions before promoting a field).
+   */
+  readonly provenance: Record<string, ReadonlyArray<PeerProfileFieldProvenance>>;
+}
+
+/**
+ * Provenance for a single profile-field mutation.
+ *
+ * Reasoner output (PR 2/5) attaches one of these every time it touches a
+ * field, so the user can audit exactly why a profile claim exists.
+ */
+export interface PeerProfileFieldProvenance {
+  /** ISO-8601 timestamp the field was set/updated by this signal. */
+  readonly observedAt: string;
+  /** Originating session id (or other source identifier). */
+  readonly sourceSessionId?: string;
+  /** Short label for the signal type (e.g. "explicit_preference"). */
+  readonly signal: string;
+  /** Optional free-form note explaining the inference. */
+  readonly note?: string;
+}
+
+/**
+ * One row of the append-only interaction log for a peer.
+ *
+ * Stored on disk under `peers/{id}/interactions.log.md` as a sequence of
+ * markdown bullet entries with a leading ISO-8601 timestamp. Append-only
+ * by contract — the reasoner reads this log to derive profile updates.
+ */
+export interface PeerInteractionLogEntry {
+  /** ISO-8601 timestamp the interaction occurred. */
+  readonly timestamp: string;
+  /** Originating session id, if any. */
+  readonly sessionId?: string;
+  /** Short kind label (e.g. "message", "tool_call", "preference_set"). */
+  readonly kind: string;
+  /** Free-form markdown summary of the interaction. */
+  readonly summary: string;
+}
+
+/**
+ * Regex enforced on `Peer.id`. Exported so callers can mirror validation
+ * before constructing a `Peer`.
+ *
+ * Rules:
+ *   - 1-64 characters total
+ *   - First and last character must be `[A-Za-z0-9]`
+ *   - Interior may contain `.`, `_`, `-` in addition to alphanumerics
+ *   - No leading or trailing dot/dash/underscore
+ *   - No consecutive separators (`..`, `--`, `__`, `.-`, etc.)
+ *
+ * Cursor Medium: previously the regex allowed `a..b` even though the
+ * docs claimed otherwise — a separate JS-side check enforced the rule
+ * but the standalone PATTERN was wrong for any external consumer
+ * relying on it. Tighten the regex itself so PEER_ID_PATTERN is the
+ * single source of truth: an alphanumeric, optionally followed by
+ * groups of (one separator + one-or-more alphanumerics), with the
+ * final group ending on an alphanumeric. Negative lookahead-free so
+ * it works in any JS engine.
+ */
+// CodeQL alert #75: the previous form `^[A-Za-z0-9](?:[._-]?[A-Za-z0-9]+)*$`
+// was ambiguous on alphanumeric runs because `[._-]?` could match
+// empty, letting each iteration consume 1+ alphanumerics in many
+// overlapping ways — exponential backtracking on adversarial inputs.
+// Tighten so the optional group REQUIRES a separator before each
+// subsequent alphanumeric run; no overlapping match paths, linear
+// time on any input.
+export const PEER_ID_PATTERN = /^[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*$/;
+
+/** Maximum length for `Peer.id`. */
+export const PEER_ID_MAX_LENGTH = 64;

package/src/plugin-id.ts

@@ -0,0 +1,84 @@
+/**
+ * Canonical plugin id for @remnic/plugin-openclaw.
+ *
+ * This is the identifier OpenClaw uses as a lookup key in plugins.slots.memory
+ * and plugins.entries.<id>. The legacy shim package @joshuaswarren/openclaw-engram
+ * intentionally uses a different id ("openclaw-engram") as a backwards-compat alias.
+ */
+export const PLUGIN_ID = "openclaw-remnic" as const;
+export const LEGACY_PLUGIN_ID = "openclaw-engram" as const;
+
+/** The set of plugin ids that belong to Remnic (new canonical + legacy). */
+const REMNIC_PLUGIN_IDS: ReadonlySet<string> = new Set([PLUGIN_ID, LEGACY_PLUGIN_ID]);
+
+/**
+ * Resolve the Remnic plugin entry from an OpenClaw-shaped config object.
+ *
+ * Lookup order:
+ *   1. `plugins.slots.memory` — but **only** when it resolves to a known
+ *      Remnic plugin id; foreign slots are ignored so mixed-plugin installs
+ *      do not accidentally apply another plugin's config to Remnic.
+ *   2. `preferredId` — the caller's own plugin id (e.g. `"openclaw-engram"` for
+ *      the shim package); only consulted when no active slot overrides the choice.
+ *   3. `plugins.entries["openclaw-remnic"]`
+ *   4. `plugins.entries["openclaw-engram"]` (legacy backward-compat)
+ *
+ * Returns `undefined` when no Remnic entry is found.
+ *
+ * All five config-loader sites (loadPluginEntryFromFile, readPluginHooksPolicy,
+ * loadPluginConfig in access-cli.ts, loadCliPluginConfig in operator-toolkit.ts,
+ * and unwrapOpenClawEntry in materialize.cjs) delegate here so fallback order
+ * and guard logic are defined in exactly one place.
+ *
+ * @param raw - The raw OpenClaw config object.
+ * @param preferredId - The calling plugin's own id.  When present and no
+ *   `plugins.slots.memory` slot is set, this id is tried before the hardcoded
+ *   `PLUGIN_ID`/`LEGACY_PLUGIN_ID` fallbacks.  Ignored if it is not a known
+ *   Remnic plugin id (safety guard against unexpected values).
+ */
+export function resolveRemnicPluginEntry(
+  raw: unknown,
+  preferredId?: string,
+): Record<string, unknown> | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const r = raw as Record<string, unknown>;
+  const plugins =
+    r["plugins"] && typeof r["plugins"] === "object"
+      ? (r["plugins"] as Record<string, unknown>)
+      : undefined;
+  const entries =
+    plugins && plugins["entries"] && typeof plugins["entries"] === "object"
+      ? (plugins["entries"] as Record<string, unknown>)
+      : undefined;
+  if (!entries) return undefined;
+
+  const rawSlot =
+    plugins && plugins["slots"] && typeof plugins["slots"] === "object"
+      ? ((plugins["slots"] as Record<string, unknown>)["memory"] as string | undefined)
+      : undefined;
+  const activeId =
+    typeof rawSlot === "string" && REMNIC_PLUGIN_IDS.has(rawSlot)
+      ? rawSlot
+      : undefined;
+
+  // When no slot is set, honour the caller's own plugin id so shim installs
+  // (id="openclaw-engram") prefer their own entry over the canonical one.
+  const ownId =
+    !activeId &&
+    typeof preferredId === "string" &&
+    REMNIC_PLUGIN_IDS.has(preferredId)
+      ? preferredId
+      : undefined;
+
+  const candidateIds = [activeId, ownId, PLUGIN_ID, LEGACY_PLUGIN_ID].filter(
+    (id): id is string => typeof id === "string",
+  );
+
+  for (const id of candidateIds) {
+    const entry = entries[id];
+    if (entry !== undefined) {
+      return entry as Record<string, unknown>;
+    }
+  }
+  return undefined;
+}

package/src/policy-runtime.ts

@@ -0,0 +1,209 @@
+import path from "node:path";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { clamp01, clampLifecycleThreshold } from "./lifecycle.js";
+import { clampInstructionHeavyTokenCap } from "./recall-query-policy.js";
+import type { BehaviorLoopPolicyState, PluginConfig } from "./types.js";
+
+export interface RuntimePolicyValues {
+  recencyWeight?: number;
+  lifecyclePromoteHeatThreshold?: number;
+  lifecycleStaleDecayThreshold?: number;
+  cronRecallInstructionHeavyTokenCap?: number;
+}
+
+export interface RuntimePolicySnapshot {
+  version: number;
+  updatedAt: string;
+  values: RuntimePolicyValues;
+  sourceAdjustmentCount: number;
+}
+
+const RUNTIME_POLICY_VERSION = 1;
+const RUNTIME_POLICY_FILE = "policy-runtime.json";
+const RUNTIME_POLICY_PREV_FILE = "policy-runtime.prev.json";
+
+export function sanitizeRuntimePolicyValues(
+  values: RuntimePolicyValues,
+  options?: { maxStaleDecayThreshold?: number },
+): RuntimePolicyValues {
+  const out: RuntimePolicyValues = {};
+  if (typeof values.recencyWeight === "number") {
+    out.recencyWeight = clamp01(values.recencyWeight);
+  }
+  if (typeof values.lifecyclePromoteHeatThreshold === "number") {
+    out.lifecyclePromoteHeatThreshold = clampLifecycleThreshold(values.lifecyclePromoteHeatThreshold);
+  }
+  if (typeof values.lifecycleStaleDecayThreshold === "number") {
+    const staleDecayThreshold = clampLifecycleThreshold(values.lifecycleStaleDecayThreshold);
+    const maxStaleDecayThreshold = typeof options?.maxStaleDecayThreshold === "number"
+      ? clampLifecycleThreshold(options.maxStaleDecayThreshold)
+      : 1;
+    out.lifecycleStaleDecayThreshold = Math.min(staleDecayThreshold, maxStaleDecayThreshold);
+  }
+  if (typeof values.cronRecallInstructionHeavyTokenCap === "number") {
+    out.cronRecallInstructionHeavyTokenCap = clampInstructionHeavyTokenCap(
+      values.cronRecallInstructionHeavyTokenCap,
+    );
+  }
+  return out;
+}
+
+function isRuntimeParameter(parameter: string): parameter is keyof RuntimePolicyValues {
+  return (
+    parameter === "recencyWeight" ||
+    parameter === "lifecyclePromoteHeatThreshold" ||
+    parameter === "lifecycleStaleDecayThreshold" ||
+    parameter === "cronRecallInstructionHeavyTokenCap"
+  );
+}
+
+export async function readRuntimePolicySnapshot(
+  filePath: string,
+  options?: { maxStaleDecayThreshold?: number },
+): Promise<RuntimePolicySnapshot | null> {
+  try {
+    const raw = await readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<RuntimePolicySnapshot>;
+    if (
+      !parsed ||
+      typeof parsed.version !== "number" ||
+      parsed.version < 1 ||
+      typeof parsed.updatedAt !== "string" ||
+      !parsed.values ||
+      typeof parsed.values !== "object" ||
+      typeof parsed.sourceAdjustmentCount !== "number" ||
+      parsed.sourceAdjustmentCount < 0
+    ) {
+      return null;
+    }
+    return {
+      version: parsed.version,
+      updatedAt: parsed.updatedAt,
+      values: sanitizeRuntimePolicyValues(parsed.values, {
+        maxStaleDecayThreshold: options?.maxStaleDecayThreshold,
+      }),
+      sourceAdjustmentCount: parsed.sourceAdjustmentCount,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function writeSnapshotAtomic(filePath: string, snapshot: RuntimePolicySnapshot): Promise<void> {
+  const tempPath = `${filePath}.tmp`;
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(tempPath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf-8");
+  await rename(tempPath, filePath);
+}
+
+export class PolicyRuntimeManager {
+  private readonly runtimePath: string;
+  private readonly runtimePrevPath: string;
+
+  constructor(
+    private readonly memoryDir: string,
+    private readonly config: PluginConfig,
+  ) {
+    const stateDir = path.join(memoryDir, "state");
+    this.runtimePath = path.join(stateDir, RUNTIME_POLICY_FILE);
+    this.runtimePrevPath = path.join(stateDir, RUNTIME_POLICY_PREV_FILE);
+  }
+
+  async loadRuntimeValues(): Promise<RuntimePolicyValues | null> {
+    const snapshot = await readRuntimePolicySnapshot(this.runtimePath, {
+      maxStaleDecayThreshold: this.config.lifecycleArchiveDecayThreshold,
+    });
+    if (!snapshot) return null;
+    return snapshot.values;
+  }
+
+  async rollback(): Promise<boolean> {
+    const previous = await readRuntimePolicySnapshot(this.runtimePrevPath, {
+      maxStaleDecayThreshold: this.config.lifecycleArchiveDecayThreshold,
+    });
+    if (!previous) return false;
+    await writeSnapshotAtomic(this.runtimePath, {
+      ...previous,
+      updatedAt: new Date().toISOString(),
+    });
+    return true;
+  }
+
+  async applyFromBehaviorState(
+    state: BehaviorLoopPolicyState,
+  ): Promise<{ applied: boolean; rolledBack: boolean; values: RuntimePolicyValues | null; reason: string }> {
+    const adjustmentCount = state.adjustments.length;
+    if (adjustmentCount === 0) {
+      return { applied: false, rolledBack: false, values: await this.loadRuntimeValues(), reason: "no_adjustments" };
+    }
+
+    const protectedSet = new Set<string>([
+      ...this.config.behaviorLoopProtectedParams,
+      ...state.protectedParams,
+    ]);
+    const existing = await readRuntimePolicySnapshot(this.runtimePath, {
+      maxStaleDecayThreshold: this.config.lifecycleArchiveDecayThreshold,
+    });
+    const candidate: RuntimePolicyValues = {
+      recencyWeight: existing?.values.recencyWeight ?? this.config.recencyWeight,
+      lifecyclePromoteHeatThreshold:
+        existing?.values.lifecyclePromoteHeatThreshold ?? this.config.lifecyclePromoteHeatThreshold,
+      lifecycleStaleDecayThreshold:
+        existing?.values.lifecycleStaleDecayThreshold ?? this.config.lifecycleStaleDecayThreshold,
+      cronRecallInstructionHeavyTokenCap:
+        existing?.values.cronRecallInstructionHeavyTokenCap ?? this.config.cronRecallInstructionHeavyTokenCap,
+    };
+
+    for (const adjustment of state.adjustments) {
+      if (!isRuntimeParameter(adjustment.parameter)) {
+        let rolledBack = false;
+        if (existing) {
+          await writeSnapshotAtomic(this.runtimePath, existing);
+          rolledBack = true;
+        } else {
+          rolledBack = await this.rollback();
+        }
+        return {
+          applied: false,
+          rolledBack,
+          values: await this.loadRuntimeValues(),
+          reason: `invalid_parameter:${adjustment.parameter}`,
+        };
+      }
+      if (protectedSet.has(adjustment.parameter)) {
+        continue;
+      }
+      if (!Number.isFinite(adjustment.nextValue)) {
+        let rolledBack = false;
+        if (existing) {
+          await writeSnapshotAtomic(this.runtimePath, existing);
+          rolledBack = true;
+        } else {
+          rolledBack = await this.rollback();
+        }
+        return {
+          applied: false,
+          rolledBack,
+          values: await this.loadRuntimeValues(),
+          reason: `invalid_value:${adjustment.parameter}`,
+        };
+      }
+      candidate[adjustment.parameter] = adjustment.nextValue;
+    }
+
+    const sanitized = sanitizeRuntimePolicyValues(candidate, {
+      maxStaleDecayThreshold: this.config.lifecycleArchiveDecayThreshold,
+    });
+    if (existing) {
+      await writeSnapshotAtomic(this.runtimePrevPath, existing);
+    }
+    const nextSnapshot: RuntimePolicySnapshot = {
+      version: RUNTIME_POLICY_VERSION,
+      updatedAt: new Date().toISOString(),
+      values: sanitized,
+      sourceAdjustmentCount: adjustmentCount,
+    };
+    await writeSnapshotAtomic(this.runtimePath, nextSnapshot);
+    return { applied: true, rolledBack: false, values: sanitized, reason: "applied" };
+  }
+}

package/src/procedural/procedure-miner.ts

@@ -0,0 +1,150 @@
+/**
+ * Cluster causal trajectories into candidate procedure memories (issue #519).
+ */
+
+import type { PluginConfig } from "../types.js";
+import type { StorageManager } from "../storage.js";
+import type { CausalTrajectoryRecord } from "../causal-trajectory.js";
+import {
+  readCausalTrajectoryRecords,
+  filterTrajectoriesByLookbackDays,
+} from "../causal-trajectory.js";
+import { buildProcedurePersistBody, normalizeProcedureSteps, type ProcedureStep } from "./procedure-types.js";
+import { clusterByKey } from "./reinforcement-core.js";
+import { log } from "../logger.js";
+
+/** Must match truncation on `procedure_cluster` structured attribute (dedupe + storage). */
+const PROCEDURE_CLUSTER_ATTR_MAX = 500;
+
+export interface ProcedureMiningResult {
+  clustersProcessed: number;
+  proceduresWritten: number;
+  skippedReason?: string;
+}
+
+function clusterKey(record: CausalTrajectoryRecord): string {
+  const goal = record.goal.trim().toLowerCase().replace(/\s+/g, " ").slice(0, 120);
+  const refs = [...(record.entityRefs ?? [])].map((r) => r.trim().toLowerCase()).sort();
+  return `${goal}|${refs.join(",")}`;
+}
+
+function successRate(group: CausalTrajectoryRecord[]): number {
+  if (group.length === 0) return 0;
+  const ok = group.filter((g) => g.outcomeKind === "success" || g.outcomeKind === "partial").length;
+  return ok / group.length;
+}
+
+/** Derive ordered pseudo-steps from trajectory text (v1 heuristic; no tool-call array on records). */
+function pseudoStepsFromCluster(group: CausalTrajectoryRecord[]): ProcedureStep[] {
+  const sentences: string[] = [];
+  const pushUnique = (raw: string) => {
+    const t = raw.trim();
+    if (t.length < 8) return;
+    if (!sentences.includes(t)) sentences.push(t);
+  };
+  for (const g of group) {
+    const parts = [g.actionSummary, g.observationSummary, g.outcomeSummary]
+      .join(" ")
+      .split(/[.!?]\s+|;|\n+/)
+      .map((s) => s.trim())
+      .filter((s) => s.length > 12);
+    for (const p of parts) pushUnique(p);
+    if (sentences.length >= 5) break;
+  }
+  if (sentences.length < 2 && group[0]) {
+    pushUnique(`${group[0].goal.trim()} — confirm prerequisites and context.`);
+    pushUnique("Execute the planned actions, then record the outcome.");
+  }
+  return sentences.slice(0, 6).map((intent, i) => ({
+    order: i + 1,
+    intent,
+  }));
+}
+
+async function hasExistingClusterWrite(
+  storage: StorageManager,
+  cluster: string,
+): Promise<boolean> {
+  const clusterKey = cluster.slice(0, PROCEDURE_CLUSTER_ATTR_MAX);
+  const memories = await storage.readAllMemories();
+  for (const m of memories) {
+    if (m.frontmatter.category !== "procedure") continue;
+    const c = m.frontmatter.structuredAttributes?.procedure_cluster;
+    if (c === clusterKey) return true;
+  }
+  return false;
+}
+
+/**
+ * Mine recurring successful trajectories into `procedure` memories (pending_review
+ * by default; active when auto-promotion thresholds are met).
+ */
+export async function runProcedureMining(options: {
+  memoryDir: string;
+  storage: StorageManager;
+  config: PluginConfig;
+}): Promise<ProcedureMiningResult> {
+  const cfg = options.config.procedural;
+  if (!cfg?.enabled) {
+    return { clustersProcessed: 0, proceduresWritten: 0, skippedReason: "procedural_disabled" };
+  }
+  if (cfg.minOccurrences <= 0) {
+    return { clustersProcessed: 0, proceduresWritten: 0, skippedReason: "minOccurrences_zero" };
+  }
+
+  const trajectoryDir =
+    typeof options.config.causalTrajectoryStoreDir === "string" &&
+    options.config.causalTrajectoryStoreDir.trim().length > 0
+      ? options.config.causalTrajectoryStoreDir.trim()
+      : undefined;
+  const { trajectories } = await readCausalTrajectoryRecords({
+    memoryDir: options.memoryDir,
+    causalTrajectoryStoreDir: trajectoryDir,
+  });
+  const recent = filterTrajectoriesByLookbackDays(trajectories, cfg.lookbackDays);
+
+  const clusters = clusterByKey(recent, clusterKey);
+
+  let clustersProcessed = 0;
+  let proceduresWritten = 0;
+
+  for (const [key, group] of clusters) {
+    if (group.length < cfg.minOccurrences) continue;
+    const rate = successRate(group);
+    if (rate < cfg.successFloor) continue;
+
+    clustersProcessed += 1;
+
+    if (await hasExistingClusterWrite(options.storage, key)) {
+      log.debug(`procedure-miner: skip duplicate cluster key=${key.slice(0, 40)}…`);
+      continue;
+    }
+
+    const steps = normalizeProcedureSteps(pseudoStepsFromCluster(group));
+    if (steps.length < 2) continue;
+
+    const title = `When you work on goals like: ${group[0].goal.trim().slice(0, 140)}`;
+    const body = buildProcedurePersistBody(title, steps);
+
+    const promote =
+      cfg.autoPromoteEnabled === true && group.length >= cfg.autoPromoteOccurrences && rate >= cfg.successFloor;
+
+    await options.storage.writeMemory("procedure", body, {
+      source: "procedure-miner",
+      status: promote ? "active" : "pending_review",
+      tags: ["procedure-miner", "causal-trajectory"],
+      structuredAttributes: {
+        procedure_cluster: key.slice(0, PROCEDURE_CLUSTER_ATTR_MAX),
+        trajectory_ids: group
+          .map((g) => g.trajectoryId)
+          .join(",")
+          .slice(0, 1900),
+        trajectory_count: String(group.length),
+        success_rate: rate.toFixed(4),
+      },
+    });
+    proceduresWritten += 1;
+  }
+
+  return { clustersProcessed, proceduresWritten };
+}

package/src/procedural/procedure-recall.ts

@@ -0,0 +1,93 @@
+/**
+ * Intent-gated recall for active procedure memories (issue #519).
+ */
+
+import type { MemoryFile, PluginConfig } from "../types.js";
+import type { StorageManager } from "../storage.js";
+import { inferIntentFromText, intentCompatibilityScore, isTaskInitiationIntent } from "../intent.js";
+import { isActiveMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+
+function tokenOverlapScore(prompt: string, memoryText: string): number {
+  const norm = (s: string) =>
+    s
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((t) => t.length > 2);
+  const promptTokens = new Set(norm(prompt));
+  const memTokens = new Set(norm(memoryText));
+  if (promptTokens.size === 0 || memTokens.size === 0) return 0;
+  let inter = 0;
+  for (const t of promptTokens) {
+    if (memTokens.has(t)) inter++;
+  }
+  const union = new Set([...promptTokens, ...memTokens]);
+  return inter / Math.max(1, union.size);
+}
+
+function scoreProcedureForPrompt(
+  m: MemoryFile,
+  prompt: string,
+  queryIntent: ReturnType<typeof inferIntentFromText>,
+): number {
+  const memText = `${m.content}\n${(m.frontmatter.tags ?? []).join(" ")}`;
+  const jaccard = tokenOverlapScore(prompt, memText);
+  const memIntent = inferIntentFromText(m.content.slice(0, 2000));
+  const intentScore = intentCompatibilityScore(queryIntent, memIntent);
+  return jaccard * 0.55 + intentScore * 0.45;
+}
+
+/**
+ * Build markdown for the recall pipeline when procedural memory is enabled and
+ * the prompt looks like task initiation.
+ */
+export async function buildProcedureRecallSection(
+  storage: StorageManager,
+  prompt: string,
+  config: PluginConfig,
+): Promise<string | null> {
+  if (config.procedural?.enabled !== true) return null;
+  const trimmed = typeof prompt === "string" ? prompt.trim() : "";
+  if (!trimmed) return null;
+
+  const queryIntent = inferIntentFromText(trimmed);
+  if (!isTaskInitiationIntent(queryIntent)) return null;
+
+  const maxN = Math.min(
+    10,
+    Math.max(
+      1,
+      typeof config.procedural.recallMaxProcedures === "number" &&
+        Number.isFinite(config.procedural.recallMaxProcedures)
+        ? Math.floor(config.procedural.recallMaxProcedures)
+        // Safer-by-default fallback (issue #567 PR 3/5): must match
+        // config.ts's canonical default (2). Cursor review on PR #607:
+        // divergent fallbacks silently regressed the safer cap whenever
+        // the config value was missing or non-finite at this call site.
+        : 2,
+    ),
+  );
+
+  const all = await storage.readAllMemories();
+  const scored = all
+    .filter(
+      (m) =>
+        m.frontmatter.category === "procedure" &&
+        isActiveMemoryStatus(m.frontmatter.status),
+    )
+    .map((m) => ({ m, score: scoreProcedureForPrompt(m, trimmed, queryIntent) }))
+    .filter((x) => x.score > 0.04)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, maxN);
+
+  if (scored.length === 0) return null;
+
+  const blocks = scored.map(({ m, score }) => {
+    const id = m.frontmatter.id;
+    const flat = m.content.replace(/\s+/g, " ").trim();
+    const preview = flat.slice(0, 320);
+    const suffix = flat.length > 320 ? "…" : "";
+    return `### ${id} (match ${score.toFixed(2)})\n\n${preview}${suffix}`;
+  });
+
+  return `## Relevant procedures\n\n${blocks.join("\n\n")}`;
+}