matchCapabilities,

} from "./coder-capability.js";

import { knowledgeHits, knowledgeNote } from "./coder-knowledge.js";

import { memoryRecallNote, rememberTool } from "./coder-recall.js";

import { runForeignResume } from "./coder-foreign-resume.js";

import { existsSync } from "node:fs";

import { spawnSync } from "node:child_process";

        recordGap: defaultCapabilityGapRecorder(),

        onSelect,

      });

      // The session's read/write handle on the local engram ledger

      // (OpenAgentsInc/openagents#51). The `remember` tool writes the user

      // bucket through it, and the retrieval rail below recalls from it on

      // every message; the delegate fleet holds its own handle on the same

      // append-only ledger, so the two never disagree about what is written.

      const recallMemory = new CoderMemory({ projectScope: `project:${process.cwd()}` });

      let declareTools: () => void;

      declareTools = () => {

        const active = skills.active();

          // being asked for. Re-declaration per turn is what makes the tool

          // appear the turn after `/goal` sets one.

          ...(goalStore.getGoal() === undefined ? [] : [goalTool(goalStore)]),

          rememberTool(recallMemory),

          ...(setup === undefined ? [] : [delegateTool(setup.delegation)]),

          capability,

          ...visiblePlugins().map((plugin) => {

        const fromKnowledge = await knowledgeBaseNote(prompt);

        if (fromKnowledge !== undefined) notes.push(fromKnowledge);

        // Memory rides the same rail (OpenAgentsInc/openagents#51): the live

        // engram ledger is ranked against this message and what clears the

        // floor arrives as attached context — no tool call needed to recall.

        try {

          const fromMemory = memoryRecallNote(recallMemory.recallable(), prompt, Date.now());

          if (fromMemory !== undefined) notes.push(fromMemory);

        } catch {

          // The rail degrades to silence, never to a broken turn.

        }

        // The knowledge base is a rail, not a tool: it never materializes.

        const matches = matchCapabilities(catalog, prompt).filter(

          (candidate) => candidate.entry.name !== "knowledge_base",

} from "./memory/index.js";

import { Schema as S } from "effect";

import type { RecallableMemory } from "./coder-recall.js";

/**

 * The coder's own memory: a local, append-only ledger of signed engrams.

 *

    return projectedValue(this.projection(), slug);

  }

  /**

   * Store one fact the reader explicitly asked to have remembered — the user

   * bucket's write path (OpenAgentsInc/openagents#51). The slug derives from

   * the content, so remembering the same sentence twice supersedes the prior

   * event under its slug rather than forking the chain into refusal. The

   * value still passes the redaction guard inside `record`; a hard-unsafe

   * fact stores nothing and this returns undefined.

   */

  remember(fact: string): EngramEvent | undefined {

    try {

      const trimmed = fact.trim().slice(0, 1000);

      if (trimmed.length === 0) return undefined;

      const slug = `user/${engramContentDigest(trimmed).slice("sha256:".length, "sha256:".length + 12)}`;

      if (this.chains().has(slug)) return this.correct(slug, trimmed);

      return this.record(slug, trimmed, "user-note");

    } catch {

      // Memory must never break a turn; a fact that could not be written is

      // reported as undefined and the tool says so in words.

      return undefined;

    }

  }

  /**

   * Everything the retrieval rail may surface, live values only: the user

   * bucket (slugs under `user/`, explicitly asked for) and the learned bucket

   * (slugs under `heuristic/`, what consolidation distilled, each carrying its

   * slug and supporting episode slugs as provenance so a wrong learning can be

   * superseded by name). Harvest episodes stay out — they are raw material,

   * not conclusions. Never throws: an empty, missing, corrupt, or unreadable

   * ledger is simply no memories.

   */

  recallable(): ReadonlyArray<RecallableMemory> {

    try {

      const memories: Array<RecallableMemory> = [];

      for (const { body, createdAtMs } of this.living()) {

        if (body.value === null) continue;

        if (body.slug.startsWith("user/")) {

          memories.push({

            bucket: "user",

            ref: body.slug,

            text: body.value,

            recordedAtMs: createdAtMs,

          });

        } else if (body.slug.startsWith("heuristic/")) {

          memories.push({

            bucket: "learned",

            ref: body.slug,

            text: body.value,

            recordedAtMs: createdAtMs,

            confidence: confidenceOf(body.openagents.entityId),

            provenance: [...body.openagents.derivedFromSlugs],

          });

        }

      }

      return memories;

    } catch {

      // The rail degrades to silence, never to a broken turn.

      return [];

    }

  }

  /**

   * The harvested ledger entries currently alive in the engram stream.

   *

/**

 * The memory rail (OpenAgentsInc/openagents#51): the harness recalls from the

 * local engram ledger on every incoming message and attaches what qualifies to

 * the outgoing turn as a bounded note. The model never calls a tool to

 * remember — by the time it writes, what this agent already holds is in front

 * of it, labelled by bucket, kind, and age, the same way the knowledge base

 * (#49) and the capability catalog (#42) already ride this rail.

 *

 * Two buckets, kept distinct in the note because their authority differs:

 *

 * - `user`: facts the reader explicitly asked to have remembered. An explicit

 *   request to remember is standing consent to be reminded, so these attach

 *   whenever they exist — the acceptance case is precisely a preference

 *   ("I use pnpm, not npm") that shares no vocabulary with the message that

 *   needs it ("install the deps").

 * - `learned`: what consolidation distilled from past sessions. A distilled

 *   heuristic is a guess about the reader, not a promise from them, so it must

 *   at least share vocabulary with the message before it interrupts, and it is

 *   surfaced with provenance — its ledger slug and the episode count under

 *   it — so a wrong learning can be traced and superseded through the existing

 *   superseding-event path rather than argued with.

 *

 * Ranking and packing reuse the owned ranking module (salience recall,

 * token-budget packing); nothing here re-derives an ordering of its own. The

 * note builder is pure, and the rail around it degrades to silence, never to

 * a broken turn.

 */

import { estimateTokens, packWithinBudget, recallOrderBySalience } from "./memory/ranking.js";

import type { CoderTool } from "./coder-tools.js";

/** One live ledger memory as the store offers it to the rail. */

export interface RecallableMemory {

  readonly bucket: "user" | "learned";

  /**

   * The ledger slug — the handle a correction is filed under. For a learned

   * memory this is what the note surfaces so a wrong heuristic can be

   * superseded by name.

   */

  readonly ref: string;

  readonly text: string;

  /** When the live revision of this memory was recorded, epoch milliseconds. */

  readonly recordedAtMs: number;

  /** Consolidation's confidence in a learned memory; absent for user notes. */

  readonly confidence?: number;

  /** The episode slugs a learned memory was distilled from. */

  readonly provenance?: ReadonlyArray<string>;

}

/**

 * The salience a memory needs before it is worth attaching. A user note always

 * clears it; a learned heuristic clears it only with lexical overlap lifting

 * it past its confidence base.

 */

export const MEMORY_ATTACH_FLOOR = 0.5;

/** Most memories one note carries; more is noise, not context. */

export const MEMORY_NOTE_LIMIT = 5;

/** The note's token budget, enforced by the owned packer. */

export const MEMORY_NOTE_BUDGET_TOKENS = 320;

/** A memory's share of one line; a runaway value is clipped, not dropped. */

const TEXT_BOUND = 300;

const clipped = (text: string): string =>

  text.length <= TEXT_BOUND ? text : `${text.slice(0, TEXT_BOUND - 1).trimEnd()}…`;

/** Lowercased words of three letters or more; the rest is noise. */

const tokensOf = (text: string): string[] =>

  text

    .toLowerCase()

    .split(/[^a-z0-9]+/)

    .filter((word) => word.length >= 3);

/**

 * The salience fed to the owned recall ordering. A user note starts at 1 —

 * explicitly asked for, always above the floor — and overlap only sharpens its

 * rank. A learned heuristic with no overlap scores 0 and stays silent; with

 * overlap it starts from consolidation's confidence.

 */

const salienceOf = (memory: RecallableMemory, hits: number): number =>

  memory.bucket === "user"

    ? 1 + hits * 0.25

    : hits === 0

      ? 0

      : (memory.confidence ?? 0.5) + hits * 0.25;

/** A coarse human age: "new" under a minute, then minutes, hours, days. */

const agePhrase = (ageMs: number): string => {

  const ms = Math.max(0, ageMs);

  if (ms < 60_000) return "new";

  const minutes = Math.floor(ms / 60_000);

  if (minutes < 60) return `${minutes}m old`;

  const hours = Math.floor(minutes / 60);

  if (hours < 24) return `${hours}h old`;

  return `${Math.floor(hours / 24)}d old`;

};

const line = (memory: RecallableMemory, nowMs: number): string => {

  const age = agePhrase(nowMs - memory.recordedAtMs);

  if (memory.bucket === "user") {

    return `- (user note, ${age}) ${clipped(memory.text)}`;

  }

  const episodes = memory.provenance?.length ?? 0;

  const support = episodes === 0 ? "" : `, from ${episodes} episode${episodes === 1 ? "" : "s"}`;

  return `- (learned heuristic ${memory.ref}, ${age}${support}) ${clipped(memory.text)}`;

};

/**

 * The note for one message, or nothing when no memory clears the floor.

 *

 * Selection is the owned ranking module end to end: the floor filters, salience

 * recall orders (salience plus recency), the limit is the top-K, and the token

 * budget is enforced by the owned packer over the rendered lines. Pure and

 * deterministic: equal inputs give an equal note.

 */

export const memoryRecallNote = (

  memories: ReadonlyArray<RecallableMemory>,

  prompt: string,

  nowMs: number,

): string | undefined => {

  if (memories.length === 0) return undefined;

  const terms = tokensOf(prompt);

  const scored = memories

    .map((memory, index) => {

      const haystack = new Set(tokensOf(memory.text));

      const hits = terms.filter((term) => haystack.has(term)).length;

      // The ref fed to the ranking module is positional, not the ledger slug:

      // two memories may legitimately share a slug prefix, and the ranking

      // contract wants refs unique within one call.

      return { memory, ref: `m${index}`, salience: salienceOf(memory, hits) };

    })

    .filter((candidate) => candidate.salience >= MEMORY_ATTACH_FLOOR);

  if (scored.length === 0) return undefined;

  const byRef = new Map(scored.map((candidate) => [candidate.ref, candidate]));

  const ordered = recallOrderBySalience(

    scored.map((candidate) => ({

      ref: candidate.ref,

      salience: candidate.salience,

      lastUsedAt: candidate.memory.recordedAtMs,

    })),

    nowMs,

  ).slice(0, MEMORY_NOTE_LIMIT);

  const lines = new Map(ordered.map((ref) => [ref, line(byRef.get(ref)!.memory, nowMs)] as const));

  const packed = packWithinBudget(

    ordered.map((ref) => ({

      ref,

      priority: byRef.get(ref)!.salience,

      tokens: estimateTokens(`${lines.get(ref) ?? ""}\n`),

    })),

    MEMORY_NOTE_BUDGET_TOKENS,

  );

  const included = new Set(packed.included);

  const kept = ordered.filter((ref) => included.has(ref));

  if (kept.length === 0) return undefined;

  return (

    "[From memory — what this agent already holds about this reader and this work. " +

    "`user` entries were explicitly asked for; `learned` entries were distilled from " +

    "earlier sessions and can be wrong — a wrong one is superseded under its named slug, " +

    "never argued with:\n" +

    kept.map((ref) => lines.get(ref) ?? "").join("\n") +

    "]"

  );

};

/**

 * The explicit write path for the user bucket. The tool exists only so the

 * reader's "remember that …" lands in the ledger; recall never goes through

 * it — the rail attaches memories without a call. Explicit only, never

 * inferred: the description tells the model to use it solely on a direct

 * request, and everything it stores is labelled `user` on the way back out.

 */

export const rememberTool = (memory: { remember(fact: string): unknown }): CoderTool => ({

  name: "remember",

  description:

    "Store one fact the reader explicitly asked to have remembered, such as " +

    '"remember that I use pnpm, not npm". Call this only when the reader directly asks ' +

    "for something to be remembered — never to record your own inferences or ambient " +

    "observations. Stored facts are recalled automatically on later messages; no tool " +

    "call is needed to read them back.",

  parameters: {

    type: "object",

    properties: {

      fact: {

        type: "string",

        description: "The fact to remember, in one bounded sentence, as the reader stated it.",

      },

    },

    required: ["fact"],

  },

  run: async (args: Record<string, unknown>): Promise<string> => {

    const fact = typeof args["fact"] === "string" ? args["fact"].trim() : "";

    if (fact.length === 0) {

      return "Nothing to remember: `fact` must be a non-empty sentence.";

    }

    try {

      const stored = memory.remember(fact);

      if (stored === undefined) {

        return (

          "That was not stored. The memory guard refuses credential-shaped material " +

          "outright; rephrase the fact without the secret if the reader still wants it kept."

        );

      }

      return "Remembered. It will be recalled automatically when a later message needs it.";

    } catch {

      // A tool reports a refusal as text rather than by throwing: the model

      // can act on words and cannot act on a turn that died.

      return "That was not stored: the memory ledger is not writable right now.";

    }

  },

});

/**

 * Memory on the retrieval rail (OpenAgentsInc/openagents#51): the note format,

 * the ranking integration with the owned ranking module, the bucket labels,

 * the `remember` write path, and the degrade-to-silence posture on an empty,

 * corrupt, or unreadable ledger. The rail itself is one call in the harness

 * (`memoryRecallNote(memory.recallable(), prompt, now)`), so these tests pin

 * that seam the way the knowledge-base tests pin theirs: the store on one

 * side, the pure note builder on the other, and the acceptance scenario end

 * to end across both.

 */

import { appendFileSync, chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";

import { tmpdir } from "node:os";

import { join } from "node:path";

import { afterEach, describe, expect, it } from "vitest";

import { CoderMemory } from "../src/coder-memory.js";

import {

  MEMORY_ATTACH_FLOOR,

  MEMORY_NOTE_LIMIT,

  memoryRecallNote,

  rememberTool,

  type RecallableMemory,

} from "../src/coder-recall.js";

const NOW = 1_756_000_000_000;

const DAY = 24 * 60 * 60 * 1000;

const dirs: Array<string> = [];

const freshDir = (): string => {

  const dir = mkdtempSync(join(tmpdir(), "coder-recall-test-"));

  dirs.push(dir);

  return dir;

};

afterEach(() => {

  for (const dir of dirs.splice(0)) {

    rmSync(dir, { recursive: true, force: true });

  }

});

const memoryAt = (dir: string, nowMs = NOW): CoderMemory =>

  new CoderMemory({ directory: dir, projectScope: "project:test", now: () => nowMs });

const userMemory = (text: string, recordedAtMs = NOW - 3 * DAY): RecallableMemory => ({

  bucket: "user",

  ref: "user/abc123def456",

  text,

  recordedAtMs,

});

const learnedMemory = (

  text: string,

  overrides: Partial<RecallableMemory> = {},

): RecallableMemory => ({

  bucket: "learned",

  ref: "heuristic/ab12cd34ef56",

  text,

  recordedAtMs: NOW - 12 * DAY,

  confidence: 0.75,

  provenance: ["harvest/aaa", "harvest/bbb"],

  ...overrides,

});

describe("the memory note format", () => {

  it("labels a user note with its bucket, kind, and age", () => {

    const note = memoryRecallNote([userMemory("I use pnpm, not npm")], "install the deps", NOW);

    expect(note).toBeDefined();

    expect(note).toContain("[From memory");

    expect(note).toContain("- (user note, 3d old) I use pnpm, not npm");

  });

  it("labels a learned heuristic with its slug, age, and episode provenance", () => {

    const note = memoryRecallNote(

      [learnedMemory("prefer ranged reads over full file dumps")],

      "read the config file with a ranged read",

      NOW,

    );

    expect(note).toBeDefined();

    expect(note).toContain(

      "- (learned heuristic heuristic/ab12cd34ef56, 12d old, from 2 episodes) " +

        "prefer ranged reads over full file dumps",

    );

  });

  it("keeps the two buckets distinct in one note", () => {

    const note = memoryRecallNote(

      [

        userMemory("I use pnpm, not npm"),

        learnedMemory("install dependencies before running tests"),

      ],

      "install the project dependencies",

      NOW,

    );

    expect(note).toContain("(user note,");

    expect(note).toContain("(learned heuristic heuristic/");

  });

  it("says nothing when there are no memories at all", () => {

    expect(memoryRecallNote([], "install the deps", NOW)).toBeUndefined();

  });

});

describe("ranking on the rail", () => {

  it("always attaches a user note, even with no lexical overlap", () => {

    // The acceptance scenario: the remembered preference shares no vocabulary

    // with the message that needs it, and it must still arrive.

    const note = memoryRecallNote([userMemory("I use pnpm, not npm")], "install the deps", NOW);

    expect(note).toContain("pnpm");

  });

  it("stays silent on a learned heuristic with no overlap with the message", () => {

    const note = memoryRecallNote(

      [learnedMemory("prefer ranged reads over full file dumps")],

      "deploy the site",

      NOW,

    );

    expect(note).toBeUndefined();

  });

  it("drops a learned heuristic whose salience stays under the floor", () => {

    // One overlap hit at rock-bottom confidence: 0.1 + 0.25 < the 0.5 floor.

    const weak = learnedMemory("deploy carefully", { confidence: 0.1 });

    expect(memoryRecallNote([weak], "deploy the site", NOW)).toBeUndefined();

    expect(MEMORY_ATTACH_FLOOR).toBe(0.5);

  });

  it("ranks the memory that overlaps the message above the one that does not", () => {

    const note = memoryRecallNote(

      [

        userMemory("my timezone is UTC+2"),

        { ...userMemory("I use pnpm for installing deps"), ref: "user/fff" },

      ],

      "install the deps",

      NOW,

    );

    expect(note).toBeDefined();

    const pnpmAt = (note ?? "").indexOf("pnpm");

    const timezoneAt = (note ?? "").indexOf("timezone");

    expect(pnpmAt).toBeGreaterThan(-1);

    expect(timezoneAt).toBeGreaterThan(-1);

    expect(pnpmAt).toBeLessThan(timezoneAt);

  });

  it("carries at most the top-K memories and stays inside the token budget", () => {

    const many = Array.from({ length: 12 }, (_, index) => ({

      ...userMemory(`standing preference number ${index} about tooling`),

      ref: `user/${index}`,

      recordedAtMs: NOW - index * DAY,

    }));

    const note = memoryRecallNote(many, "anything at all", NOW);

    expect(note).toBeDefined();

    expect((note ?? "").split("\n- ").length - 1).toBeLessThanOrEqual(MEMORY_NOTE_LIMIT);

    // The budget bounds the note: 320 tokens at ~4 chars each, plus header.

    expect((note ?? "").length).toBeLessThan(2000);

  });

  it("clips a runaway memory value rather than letting it flood the turn", () => {

    const note = memoryRecallNote([userMemory(`x${"y".repeat(5000)}`)], "anything", NOW);

    expect(note).toBeDefined();

    expect((note ?? "").length).toBeLessThan(1000);

    expect(note).toContain("…");

  });

});

describe("the remember write path", () => {

  it("writes a user-bucket engram the rail reads back", async () => {

    const dir = freshDir();

    const memory = memoryAt(dir);

    const tool = rememberTool(memory);

    const reply = await tool.run({ fact: "I use pnpm, not npm" }, new AbortController().signal);

    expect(reply).toContain("Remembered");

    // A fresh handle on the same ledger sees the fact: the write is on disk,

    // not in the instance.

    const recalled = memoryAt(dir).recallable();

    expect(recalled).toHaveLength(1);

    expect(recalled[0]?.bucket).toBe("user");

    expect(recalled[0]?.ref.startsWith("user/")).toBe(true);

    expect(recalled[0]?.text).toBe("I use pnpm, not npm");

  });

  it("remembering the same fact twice supersedes instead of forking the chain", () => {

    const dir = freshDir();

    const memory = memoryAt(dir);

    expect(memory.remember("I use pnpm, not npm")).toBeDefined();

    expect(memory.remember("I use pnpm, not npm")).toBeDefined();

    const recalled = memory.recallable();

    expect(recalled).toHaveLength(1);

    expect(recalled[0]?.text).toBe("I use pnpm, not npm");

  });

  it("refuses credential-shaped material in words, not by throwing", async () => {

    const dir = freshDir();

    const tool = rememberTool(memoryAt(dir));

    const reply = await tool.run(

      { fact: "the token is oa_pat_abc123def456ghi789jkl012" },

      new AbortController().signal,

    );

    expect(reply).toContain("not stored");

    expect(memoryAt(dir).recallable()).toHaveLength(0);

  });

  it("refuses an empty fact in words", async () => {

    const tool = rememberTool(memoryAt(freshDir()));

    expect(await tool.run({ fact: "   " }, new AbortController().signal)).toContain(

      "Nothing to remember",

    );

    expect(await tool.run({}, new AbortController().signal)).toContain("Nothing to remember");

  });

});

describe("recall from the ledger", () => {

  it("surfaces a distilled heuristic as learned, with confidence and provenance", () => {

    const dir = freshDir();

    const memory = memoryAt(dir);

    memory.record(

      "heuristic/ab12cd34ef56",

      "install dependencies before running the tests",

      "synth-1#0.750",

      ["harvest/aaa", "harvest/bbb"],

    );

    const recalled = memory.recallable();

    expect(recalled).toHaveLength(1);

    expect(recalled[0]?.bucket).toBe("learned");

    expect(recalled[0]?.confidence).toBeCloseTo(0.75);

    expect(recalled[0]?.provenance).toEqual(["harvest/aaa", "harvest/bbb"]);

  });

  it("leaves harvest episodes out of the rail", () => {

    const dir = freshDir();

    const memory = memoryAt(dir);

    memory.record("harvest/abc123def456", "some raw finding", "child-1");

    expect(memory.recallable()).toHaveLength(0);

  });

  it("an empty ledger recalls nothing, without an error", () => {

    const memory = memoryAt(freshDir());

    expect(memory.recallable()).toEqual([]);

    expect(memoryRecallNote(memory.recallable(), "install the deps", NOW)).toBeUndefined();

  });

  it("a corrupt ledger recalls nothing, without an error", () => {

    const dir = freshDir();

    const memory = memoryAt(dir);

    memory.remember("I use pnpm, not npm");

    appendFileSync(join(dir, "engrams.jsonl"), 'not json at all\n{"half": \n');

    const recalled = memoryAt(dir).recallable();

    // The junk lines are dropped; the verified engram survives them.

    expect(recalled).toHaveLength(1);

    // A ledger that is nothing but junk is simply no memories.

    writeFileSync(join(dir, "engrams.jsonl"), "garbage\n{}\n[1,2]\n");

    expect(memoryAt(dir).recallable()).toEqual([]);

  });

  it.skipIf(process.getuid?.() === 0)(

    "an unreadable ledger recalls nothing, without an error",

    () => {

      const dir = freshDir();

      const memory = memoryAt(dir);

      memory.remember("I use pnpm, not npm");

      chmodSync(join(dir, "engrams.jsonl"), 0o000);

      try {

        expect(memoryAt(dir).recallable()).toEqual([]);

      } finally {

        chmodSync(join(dir, "engrams.jsonl"), 0o600);

      }

    },

  );

});

describe("end to end across the seam", () => {

  it("a remembered preference answers a later unrelated-sounding turn", async () => {

    // The acceptance scenario for #51: the reader says "remember I use pnpm,

    // not npm"; the model calls the remember tool once. A later "install the

    // deps" turn gets the memory as attached context from the rail alone.

    const dir = freshDir();

    const tool = rememberTool(memoryAt(dir));

    await tool.run({ fact: "I use pnpm, not npm" }, new AbortController().signal);

    const later = memoryAt(dir, NOW + 2 * DAY);

    const note = memoryRecallNote(later.recallable(), "install the deps", NOW + 2 * DAY);

    expect(note).toBeDefined();

    expect(note).toContain("(user note, 2d old) I use pnpm, not npm");

  });

});