@remnic/core 9.3.712 → 9.3.714

package/src/recall-state.ts

@@ -502,3 +502,102 @@ export class TierMigrationStatusStore {
     }
   }
 }
+
+
+/**
+ * Per-session bounded history of recent recall memory-id sets, used ONLY by
+ * handle resolution (issue #1582). Distinct from {@link LastRecallStore} —
+ * that keeps ONE last snapshot per session; this keeps a small ring (depth N)
+ * of the memory-id arrays a session has recalled, newest first, so a handle
+ * cited in a later turn still resolves even after a newer recall displaced the
+ * "last" snapshot.
+ *
+ * Deliberately lightweight: stores only `string[]` per entry (no full
+ * snapshot), capped at `depth` per session and 50 sessions total (rule 27
+ * slice/cap guards). Misses are acceptable and tagged at resolution time.
+ */
+export class RecallHandleHistoryStore {
+  private readonly statePath: string;
+  private readonly writeStateFile: StateFileWriter;
+  private state: Record<string, Array<{ at: string; ids: string[] }>> = {};
+  private writeChain: Promise<void> = Promise.resolve();
+  private readonly maxDepth: number;
+
+  constructor(memoryDir: string, options: { writeStateFile?: StateFileWriter; maxDepth?: number } = {}) {
+    this.statePath = path.join(memoryDir, "state", "handle_history.json");
+    this.writeStateFile =
+      options.writeStateFile ??
+      (async (filePath, content) => {
+        await writeFileAtomically(filePath, content);
+      });
+    this.maxDepth =
+      typeof options.maxDepth === "number" && Number.isFinite(options.maxDepth)
+        ? Math.max(1, Math.min(50, Math.floor(options.maxDepth)))
+        : 5;
+  }
+
+  async load(): Promise<void> {
+    try {
+      const raw = await readFile(this.statePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") this.state = parsed as typeof this.state;
+    } catch {
+      this.state = {};
+    }
+  }
+
+  /**
+   * Record one recall's admitted memory ids for a session, newest first.
+   * The ring is capped at {@link maxDepth}; older entries drop off the tail.
+   */
+  async record(sessionKey: string, memoryIds: readonly string[]): Promise<void> {
+    if (!sessionKey) return;
+    const ids = memoryIds.filter((id): id is string => typeof id === "string" && id.length > 0);
+    const entry = { at: new Date().toISOString(), ids };
+    const prior = this.state[sessionKey] ?? [];
+    const next = [entry, ...prior].slice(0, this.maxDepth);
+    this.state[sessionKey] = next;
+    this.capSessions();
+    try {
+      await this.flush();
+    } catch (err) {
+      log.debug(`recall handle history write failed: ${err}`);
+    }
+  }
+
+  /**
+   * Return the memory-id arrays for a session, newest first, capped at `depth`.
+   * Empty array when the session has no recorded history.
+   */
+  recent(sessionKey: string, depth: number = this.maxDepth): Array<readonly string[]> {
+    const entries = this.state[sessionKey];
+    if (!entries || entries.length === 0) return [];
+    const limit = Math.max(0, Math.min(depth, entries.length));
+    return entries.slice(0, limit).map((e) => e.ids);
+  }
+
+  /** Test seam: drop all history (used by the corpus-scan hygiene test). */
+  clearForTest(): void {
+    this.state = {};
+  }
+
+  private capSessions(): void {
+    const keys = Object.keys(this.state);
+    if (keys.length <= 50) return;
+    const ordered = keys
+      .map((k) => ({ k, at: this.state[k]?.[0]?.at ?? "" }))
+      .sort((a, b) => b.at.localeCompare(a.at));
+    for (const doomed of ordered.slice(50)) {
+      delete this.state[doomed.k];
+    }
+  }
+
+  private flush(): Promise<void> {
+    const run = this.writeChain.catch(() => undefined).then(async () => {
+      await mkdir(path.dirname(this.statePath), { recursive: true });
+      await this.writeStateFile(this.statePath, JSON.stringify(this.state, null, 2));
+    });
+    this.writeChain = run.then(() => undefined, () => undefined);
+    return run;
+  }
+}

package/src/sanitize.ts

@@ -56,3 +56,9 @@ export function sanitizeMemoryContent(text: string): SanitizeResult {
 export function isSafeMemoryContent(text: string): boolean {
   return sanitizeMemoryContent(text).clean;
 }
+
+// Issue #1582 hygiene §2 — handles are render-time-only tokens; when an agent
+// echoes one back into a turn, the orchestrator strips it via this name before
+// the turn enters the extraction buffer (rule 23). Re-exported from the pure
+// recall-handles module so every content-sanitization concern lives here.
+export { stripHandles as stripMemoryHandles } from "./recall-handles.js";

package/src/types.ts

@@ -494,6 +494,19 @@ export interface CodingKnowledgeConfig {
   codegraphDbDir: string;
 }
 
+// ChatConfig — conversational memory inspection and correction (issue #1583).
+// Off by default — spawns LLM calls so explicit opt-in (rule 48).
+export interface ChatConfig {
+  /** Master gate. Off = no tools/endpoints/CLI registered (byte-identical, rule 39). */
+  enabled: boolean;
+  /** Routing override for the chat LLM (empty = use the default chain). */
+  model: string;
+  /** Max tool calls per user turn before partial-reply fallback (rule 34). */
+  maxToolCallsPerTurn: number;
+  /** Hours after which idle chat session state is cleaned up. */
+  sessionTtlHours: number;
+}
+
 /**
  * Session-scoped coding context. Produced by `resolveGitContext()` in the
  * connector layer and attached to a session so that recall + write paths can
@@ -1091,6 +1104,9 @@ export interface PluginConfig {
   // (rule 39).
   codingKnowledge: CodingKnowledgeConfig;
   heartbeat: HeartbeatConfig;
+  // Conversational memory inspection and correction (issue #1583). Off by
+  // default — byte-identical pre-feature when enabled === false (rule 39).
+  chat: ChatConfig;
   slotBehavior: SlotBehaviorConfig;
   codexCompat: CodexCompatConfig;
   /**
@@ -1650,6 +1666,19 @@ export interface PluginConfig {
    * benchmarking (issue #564 PR 3).
    */
   recallReasoningTraceBoostEnabled: boolean;
+  /**
+   * Issue #1582 — append stable short handles (`[m:4f2a]`) to injected memory
+   * lines at recall render time. Default false: off = byte-identical injection
+   * (rule 39). Token cost ~9 chars/memory; flip the default only with #1574
+   * evidence that answer quality is unaffected (rule 55).
+   */
+  recallMemoryHandles: boolean;
+  /**
+   * Issue #1582 — how many recent per-session recall snapshots (newest first)
+   * handle resolution searches. Older-than-N snapshots are not searched and a
+   * miss is tagged rather than widening the window.
+   */
+  recallHandleSnapshotDepth: number;
   qmdRecallCacheTtlMs: number;
   qmdRecallCacheStaleTtlMs: number;
   qmdRecallCacheMaxEntries: number;