dsh-context-memory 0.7.1 → 0.10.0

package/lib/recall.js

@@ -11,6 +11,10 @@
  * encoding that in one number is what makes "recall the most reliable thing you know"
  * expressible at all.
  *
+ * A memory a check *contradicted*, however, is not a low-scoring candidate — it is the
+ * wrong answer. It is filtered out here rather than down-weighted, because no amount of
+ * lexical overlap makes "the build uses yarn" useful once `package.json` disagrees.
+ *
  * @module context-memory/recall
  */
 import { normaliseSubject } from './identity.js';
@@ -21,14 +25,52 @@ const STOP_WORDS = new Set([
     'their', 'them', 'they', 'this', 'to', 'was', 'we', 'were', 'what', 'when', 'where',
     'which', 'who', 'will', 'with', 'you', 'your',
 ]);
-/** Split a query into distinct signal-bearing tokens. */
+/**
+ * Characters treated as part of a Latin word.
+ *
+ * Everything else — including punctuation, whitespace, and every CJK code point — splits
+ * a Latin token. CJK is handled by its own branch below rather than here.
+ */
+const LATIN_WORD = /[a-z0-9_.-]+/g;
+/**
+ * A run of CJK characters.
+ *
+ * Covers the unified ideographs (the bulk of Chinese), the extension-A block, and the
+ * compatibility ideographs. Kana and Hangul are deliberately excluded: they are not the
+ * scripts this plugin's second language is written in, and including them would produce
+ * 2-grams that match nothing.
+ */
+const CJK_RUN = /[㐀-䶿一-鿿豈-﫿]+/g;
+/** Shortest CJK run that still yields a usable 2-gram. */
+const CJK_MIN_RUN = 2;
+/**
+ * Split a query into distinct signal-bearing tokens.
+ *
+ * Latin text is split on word boundaries as before. CJK text has no spaces, so a
+ * whitespace tokenizer discards it entirely — which made recall return nothing for every
+ * Chinese query while capture happily stored Chinese statements. Each CJK run is instead
+ * cut into overlapping 2-grams: two characters is the smallest unit that carries meaning
+ * in Chinese ("构建" does, "建" alone does not), and a 2-gram index needs no dictionary,
+ * no dependency, and no runtime model.
+ *
+ * A genuine word longer than two characters overlaps into several grams, so a query and a
+ * memory that share one word still match even when the surrounding wording differs.
+ */
 export function tokenize(text) {
+    const lowered = text.toLowerCase();
     const seen = new Set();
-    for (const raw of text.toLowerCase().split(/[^a-z0-9_.-]+/)) {
+    for (const raw of lowered.match(LATIN_WORD) ?? []) {
         if (raw.length < 2 || STOP_WORDS.has(raw))
             continue;
         seen.add(raw);
     }
+    for (const run of lowered.match(CJK_RUN) ?? []) {
+        if (run.length < CJK_MIN_RUN)
+            continue;
+        for (let index = 0; index + CJK_MIN_RUN <= run.length; index += 1) {
+            seen.add(run.slice(index, index + CJK_MIN_RUN));
+        }
+    }
     return [...seen];
 }
 /** How much each part of the score can contribute. Sums to 1. */
@@ -39,6 +81,56 @@ const WEIGHTS = {
 };
 /** A memory older than this contributes no recency credit. */
 const RECENCY_HORIZON_MS = 90 * 24 * 60 * 60 * 1000;
+/**
+ * The text a query is matched against, normalised once per memory.
+ *
+ * Keyed on the memory object, which the fold produces once and then reuses, so this is
+ * one normalisation per memory rather than one per memory per query — the lower-casing
+ * and three regex passes in `normaliseSubject` were being redone on every call, for
+ * every memory, on every step. A `WeakMap` rather than a field on `MemoryState` so the
+ * public shape (which the panel renders and the log emits) does not grow a derived
+ * value that could be stale for a hand-built object.
+ */
+const SEARCHABLE_TEXT = new WeakMap();
+function searchableText(memory) {
+    const cached = SEARCHABLE_TEXT.get(memory);
+    if (cached !== undefined)
+        return cached;
+    const value = normaliseSubject(`${memory.subject} ${memory.text}`);
+    SEARCHABLE_TEXT.set(memory, value);
+    return value;
+}
+/**
+ * Inverse document frequency over the population being ranked.
+ *
+ * Why this exists: plain overlap (`matched / tokens`) gives "项目" and "构建" the same
+ * weight. In a log about one project the first appears in nearly every memory and
+ * matches everything, so a query that also names a rare term ("pnpm") is diluted by the
+ * common ones. IDF is the standard correction — a term that appears in fewer memories
+ * carries more of the query meaning.
+ *
+ * Computed per `recall()` call over the filtered population, so the corpus is exactly the
+ * set of candidates being ranked: no global statistics to keep in sync, and no behaviour
+ * change when every term is equally common (equal weights reduce the weighted fraction
+ * to `matched / tokens`).
+ */
+export function buildIdf(memories, tokens) {
+    const idf = new Map();
+    if (memories.length === 0 || tokens.length === 0)
+        return idf;
+    const texts = memories.map((memory) => searchableText(memory));
+    const n = texts.length;
+    for (const token of tokens) {
+        let df = 0;
+        for (const text of texts)
+            if (text.includes(token))
+                df += 1;
+        // Smoothed IDF, always positive: a term in every document scores ~0 rather than
+        // going negative and inverting the ranking.
+        idf.set(token, Math.log(1 + (n - df + 0.5) / (df + 0.5)));
+    }
+    return idf;
+}
 /**
  * Score how relevant one memory is to a query.
  *
@@ -48,30 +140,98 @@ const RECENCY_HORIZON_MS = 90 * 24 * 60 * 60 * 1000;
  * passed a check or it did not, and giving partial credit for "was checked once and has
  * not been rechecked" would reward staleness.
  */
-export function scoreMemory(memory, tokens, now = Date.now()) {
-    const subject = normaliseSubject(`${memory.subject} ${memory.text}`);
+export function scoreMemory(memory, tokens, now = Date.now(), idf) {
+    const subject = searchableText(memory);
     const matched = tokens.filter((token) => subject.includes(token));
-    const overlap = tokens.length === 0 ? 0 : matched.length / tokens.length;
+    // Overlap is the fraction of the query's *signal* that this memory covers. Without an
+    // IDF map it is the plain ratio; with one, each matched term contributes in proportion
+    // to how rare it is across the population (see buildIdf). The denominator keeps every
+    // query term — one that matches nothing still counts against the memory, which is what
+    // stops a stray rare word from inflating a score.
+    let overlap;
+    if (idf === undefined || tokens.length === 0) {
+        overlap = tokens.length === 0 ? 0 : matched.length / tokens.length;
+    }
+    else {
+        let weightTotal = 0;
+        let weightMatched = 0;
+        const matchedSet = new Set(matched);
+        for (const token of tokens) {
+            const weight = idf.get(token) ?? 1;
+            weightTotal += weight;
+            if (matchedSet.has(token))
+                weightMatched += weight;
+        }
+        overlap = weightTotal === 0 ? 0 : weightMatched / weightTotal;
+    }
     const age = Math.max(0, now - memory.createdAt);
     const recency = Math.max(0, 1 - age / RECENCY_HORIZON_MS);
     const verified = memory.verification?.outcome === 'passed' ? 1 : 0;
     const score = overlap * WEIGHTS.overlap + recency * WEIGHTS.recency + verified * WEIGHTS.verification;
-    const why = `overlap ${matched.length}/${tokens.length}, recency ${recency.toFixed(2)}, ${verified ? 'verified' : 'unverified'}`;
+    const idfPart = idf === undefined ? '' : ` (idf ${overlap.toFixed(2)})`;
+    const why = `overlap ${matched.length}/${tokens.length}${idfPart}, recency ${recency.toFixed(2)}, ${verified ? 'verified' : 'unverified'}`;
     return { score, matched, why };
 }
 /**
- * Rank active memories against a query.
+ * Whether the world has denied this memory.
+ *
+ * Distinct from both `superseded` (a person retired it) and `broken` (the check could not
+ * run). Only a check that ran and failed counts: an unusable check says nothing about the
+ * memory, and treating it as a denial is how a typo would erase a true statement.
+ */
+export function isContradicted(memory) {
+    return memory.status === 'active' && memory.verification?.outcome === 'violated';
+}
+/**
+ * Whether a memory belongs to the population `target` names.
  *
- * Superseded memories are excluded here rather than filtered by the caller: a memory
- * that was replaced is not a weaker answer, it is a wrong one, and ranking it anywhere
- * would put it back in front of the agent.
+ * Exported because two callers need the same answer and must not drift: ranking uses it
+ * to filter, and the memory service uses it to answer "what is in this population" for
+ * the pull tool. A second definition of "guidance" is how the push and pull paths would
+ * end up disagreeing about what the plugin considers offerable.
  */
-export function recall(memories, query, limit = 5, now = Date.now()) {
+export function inTarget(memory, target) {
+    switch (target) {
+        case 'guidance': return memory.status === 'active' && !isContradicted(memory);
+        case 'contradicted': return isContradicted(memory);
+        case 'superseded': return memory.status === 'superseded';
+        case 'all': return true;
+    }
+}
+/**
+ * Rank memories against a query.
+ *
+ * The default population is guidance: superseded and contradicted memories are excluded
+ * here rather than filtered by the caller, because one was replaced and the other was
+ * disproved. Neither is a weaker answer — both are wrong ones, and ranking them anywhere
+ * would put them back in front of the agent unasked.
+ *
+ * `target` exists for the opposite caller: a model that explicitly asks what was
+ * recorded, or what a check disproved. Widening it is a deliberate, per-call decision
+ * and never the default, because the two paths want different answers to "what is
+ * true" — the push path wants guidance, the pull path wants the log.
+ */
+export function recall(memories, query, limit = 5, now = Date.now(), target = 'guidance') {
     const tokens = tokenize(query);
-    return memories
-        .filter((memory) => memory.status === 'active')
-        .map((memory) => ({ memory, ...scoreMemory(memory, tokens, now) }))
+    const population = memories.filter((memory) => inTarget(memory, target));
+    const idf = buildIdf(population, tokens);
+    const hits = population
+        .map((memory) => ({ memory, ...scoreMemory(memory, tokens, now, idf) }))
+        // A query with no signal-bearing tokens matches nothing rather than everything: an
+        // empty query is a question about nothing, and answering it with the whole log would
+        // make every ranking unexplainable.
         .filter((hit) => hit.matched.length > 0)
-        .sort((a, b) => b.score - a.score || b.memory.createdAt - a.memory.createdAt)
-        .slice(0, limit);
+        .sort((a, b) => b.score - a.score || b.memory.createdAt - a.memory.createdAt);
+    // One claim, one hit. The id is derived from the statement, so the same sentence
+    // recorded in both scopes arrives twice with the same id and — by construction — the
+    // same score and the same text. Handing both to the caller would put the same line into
+    // the injected context twice and make `limit` mean "hits" instead of "memories".
+    // `scope` is still reported on the survivor, so which log holds it stays visible.
+    const seen = new Set();
+    return hits.filter((hit) => {
+        if (seen.has(hit.memory.id))
+            return false;
+        seen.add(hit.memory.id);
+        return true;
+    }).slice(0, limit);
 }

package/lib/routes.d.ts

@@ -15,4 +15,5 @@ export declare const MEMORY_RECALL_PATH = "/api/context-memory.recall";
 export declare const MEMORY_REMEMBER_PATH = "/api/context-memory.remember";
 export declare const MEMORY_FORGET_PATH = "/api/context-memory.forget";
 export declare const MEMORY_PREFS_PATH = "/api/context-memory.prefs";
+export declare const MEMORY_CANDIDATES_PATH = "/api/context-memory.candidates";
 export declare function registerMemoryRoutes(ctx: Context, memory: MemoryService): void;

package/lib/routes.js

@@ -13,6 +13,7 @@ export const MEMORY_RECALL_PATH = '/api/context-memory.recall';
 export const MEMORY_REMEMBER_PATH = '/api/context-memory.remember';
 export const MEMORY_FORGET_PATH = '/api/context-memory.forget';
 export const MEMORY_PREFS_PATH = '/api/context-memory.prefs';
+export const MEMORY_CANDIDATES_PATH = '/api/context-memory.candidates';
 export function registerMemoryRoutes(ctx, memory) {
     // Injecting rather than reading `ctx.connection` directly: a plain property access on
     // a service that was not declared throws, and the web connection is absent in headless
@@ -71,6 +72,8 @@ export function registerMemoryRoutes(ctx, memory) {
                     input.subject = body.subject;
                 if (body.kind)
                     input.kind = body.kind;
+                if (body.scope === 'user' || body.scope === 'project')
+                    input.scope = body.scope;
                 if (body.source)
                     input.source = body.source;
                 const mem = memory.remember(input);
@@ -92,12 +95,58 @@ export function registerMemoryRoutes(ctx, memory) {
                 }
                 if (!body.id)
                     return Response.json({ error: 'missing id' }, { status: 400 });
-                const ok = memory.forget(body.id, body.reason ?? 'superseded from panel', body.replacedBy);
+                const scope = body.scope === 'user' || body.scope === 'project' ? body.scope : undefined;
+                const ok = memory.forget(body.id, body.reason ?? 'superseded from panel', {
+                    ...(body.replacedBy !== undefined ? { replacedBy: body.replacedBy } : {}),
+                    ...(scope !== undefined ? { scope } : {}),
+                });
                 if (!ok)
                     return Response.json({ error: 'not found' }, { status: 404 });
                 return Response.json({ ok: true });
             },
         });
+        // Candidate decisions — accept writes a memory, dismiss records the answer.
+        //
+        // Accepting is the only path from a heuristic to the log, which is why it takes an
+        // explicit id: the caller names the proposal it is confirming, and there is no route
+        // that turns "a sentence that looked like a fact" into a memory on its own.
+        connection.fetch.register({
+            path: MEMORY_CANDIDATES_PATH,
+            methods: ['GET', 'POST'],
+            requestBody: 'buffered',
+            fetch: async (request) => {
+                if (request.method === 'GET') {
+                    return Response.json({ candidates: memory.candidates() }, { headers: { 'cache-control': 'no-store' } });
+                }
+                let body;
+                try {
+                    body = await request.json();
+                }
+                catch {
+                    return Response.json({ error: 'invalid JSON' }, { status: 400 });
+                }
+                if (body.id === undefined || body.id.length === 0)
+                    return Response.json({ error: 'missing id' }, { status: 400 });
+                if (body.action === 'dismiss') {
+                    const ok = memory.dismiss(body.id);
+                    return ok ? Response.json({ ok: true }) : Response.json({ error: 'not found' }, { status: 404 });
+                }
+                if (body.action === 'accept') {
+                    const overrides = {};
+                    if (body.text !== undefined && body.text.trim().length > 0)
+                        overrides.text = body.text;
+                    if (body.kind !== undefined)
+                        overrides.kind = body.kind;
+                    if (body.scope === 'user' || body.scope === 'project')
+                        overrides.scope = body.scope;
+                    const stored = memory.accept(body.id, overrides);
+                    return stored === undefined
+                        ? Response.json({ error: 'not found' }, { status: 404 })
+                        : Response.json(stored);
+                }
+                return Response.json({ error: 'action must be accept or dismiss' }, { status: 400 });
+            },
+        });
         // Feature switches — GET to read, POST a partial patch to set
         connection.fetch.register({
             path: MEMORY_PREFS_PATH,

package/lib/scope.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Where a memory lives.
+ *
+ * Two scopes, because "the build uses pnpm" and "answer me in Chinese" are stored in
+ * different places for different reasons. A project convention is only true inside that
+ * checkout and should travel with it; a working preference is true everywhere the user
+ * works and should not be re-stated in every repository.
+ *
+ * The scope is a property of the memory, not of the installation: one log holds both,
+ * and each entry is routed to the store its scope names. That keeps one fold and one
+ * panel while still letting the two populations move independently.
+ *
+ * @module context-memory/scope
+ */
+/**
+ * Directory names that mark the top of a project, in probe order.
+ *
+ * `package.json` is deliberately absent. It is the marker everyone reaches for and it is
+ * the wrong one: a stray `package.json` in a home directory makes every unrelated folder
+ * beneath it one project, so a scratch directory on the Desktop would share a memory log
+ * with everything else in the profile. `.git` marks a checkout, and a workspace file only
+ * appears at the top of a workspace, which is what a project root means here.
+ *
+ * This matches `dsh-agent-instructions`, whose default `projectRootMarkers` is `['.git']`.
+ */
+export declare const PROJECT_ROOT_MARKERS: readonly [".git", "pnpm-workspace.yaml"];
+/** Where the user-global log lives, under the harness home. */
+export declare function userStoreDir(): string;
+/**
+ * Find the top of the project containing `start`.
+ *
+ * Mirrors `dsh-agent-instructions`'s discovery: climb while the marker is *absent*, and
+ * stop at the first directory that carries one. The difference from `process.cwd()` is
+ * the whole point — a session started three levels down inside a monorepo is still the
+ * same project, and two directories that are not the same project must not share a log.
+ *
+ * When no marker is found anywhere on the way up, `start` is its own project — which is
+ * honest: there is no evidence that anything above it belongs to the same work.
+ *
+ * @param start - absolute directory to begin from.
+ * @returns the discovered project root, or `start` when nothing marks one.
+ */
+export declare function findProjectRoot(start: string): string;
+/** Resolve the directory a project memory is stored under. */
+export declare function resolveProjectStore(cwd?: string): string;

package/lib/scope.js

@@ -0,0 +1,75 @@
+/**
+ * Where a memory lives.
+ *
+ * Two scopes, because "the build uses pnpm" and "answer me in Chinese" are stored in
+ * different places for different reasons. A project convention is only true inside that
+ * checkout and should travel with it; a working preference is true everywhere the user
+ * works and should not be re-stated in every repository.
+ *
+ * The scope is a property of the memory, not of the installation: one log holds both,
+ * and each entry is routed to the store its scope names. That keeps one fold and one
+ * panel while still letting the two populations move independently.
+ *
+ * @module context-memory/scope
+ */
+import { statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+/**
+ * Directory names that mark the top of a project, in probe order.
+ *
+ * `package.json` is deliberately absent. It is the marker everyone reaches for and it is
+ * the wrong one: a stray `package.json` in a home directory makes every unrelated folder
+ * beneath it one project, so a scratch directory on the Desktop would share a memory log
+ * with everything else in the profile. `.git` marks a checkout, and a workspace file only
+ * appears at the top of a workspace, which is what a project root means here.
+ *
+ * This matches `dsh-agent-instructions`, whose default `projectRootMarkers` is `['.git']`.
+ */
+export const PROJECT_ROOT_MARKERS = ['.git', 'pnpm-workspace.yaml'];
+/** Where the user-global log lives, under the harness home. */
+export function userStoreDir() {
+    return dshHomePath('context-memory');
+}
+/**
+ * Find the top of the project containing `start`.
+ *
+ * Mirrors `dsh-agent-instructions`'s discovery: climb while the marker is *absent*, and
+ * stop at the first directory that carries one. The difference from `process.cwd()` is
+ * the whole point — a session started three levels down inside a monorepo is still the
+ * same project, and two directories that are not the same project must not share a log.
+ *
+ * When no marker is found anywhere on the way up, `start` is its own project — which is
+ * honest: there is no evidence that anything above it belongs to the same work.
+ *
+ * @param start - absolute directory to begin from.
+ * @returns the discovered project root, or `start` when nothing marks one.
+ */
+export function findProjectRoot(start) {
+    const origin = resolve(start);
+    let current = origin;
+    for (;;) {
+        for (const marker of PROJECT_ROOT_MARKERS) {
+            if (exists(join(current, marker)))
+                return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return origin;
+        current = parent;
+    }
+}
+/** `statSync` that answers a yes/no question without throwing on absence. */
+function exists(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the directory a project memory is stored under. */
+export function resolveProjectStore(cwd) {
+    return findProjectRoot(cwd !== undefined && isAbsolute(cwd) ? cwd : resolve('.'));
+}

package/lib/store.d.ts

@@ -11,11 +11,31 @@
  */
 import type { MemoryEvent } from './types.js';
 export declare class MemoryStore {
-    private readonly projectDir;
     private readonly dir;
     private readonly logPath;
-    constructor(projectDir: string);
+    /**
+     * The parsed log, together with the file identity it was parsed from.
+     *
+     * This is not the cache the module comment warns about. That one was rejected because
+     * it would let one process's view of history outlive the events that contradict it;
+     * this one is revalidated against the file's own size and mtime on every read, so an
+     * append by another process is seen on the next call exactly as before. What it avoids
+     * is re-parsing an unchanged file — the same log is folded several times inside one
+     * pre-step, and parsing it once per fold is the only part of that which is avoidable.
+     */
+    private cached;
+    /** @param dir - the `.memory` directory itself, already resolved for its scope. */
+    constructor(dir: string);
     get path(): string;
+    /**
+     * An identity for the file as it is right now, or null when there is no file.
+     *
+     * Size alone would miss a rewrite; mtime alone is too coarse on some Windows
+     * filesystems. Together they change on every append this process or another makes.
+     * `stat` costs a syscall; reading and parsing the file costs a syscall plus an
+     * allocation plus a JSON.parse per line, which is why this is worth doing.
+     */
+    signature(): string | null;
     append(event: MemoryEvent): void;
     /**
      * Read the whole log.
@@ -25,6 +45,9 @@ export declare class MemoryStore {
      * recoverable loss for a total one — so a torn *final* line is dropped. Corruption
      * anywhere else is a real problem and is reported rather than skipped, because
      * silently ignoring a damaged record is how a log stops being evidence.
+     *
+     * The returned array is shared with the cache: treat it as read-only.
      */
     readAll(): MemoryEvent[];
+    private parse;
 }

package/lib/store.js

@@ -9,25 +9,55 @@
  *
  * @module context-memory/store
  */
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 export class MemoryStore {
-    projectDir;
     dir;
     logPath;
-    constructor(projectDir) {
-        this.projectDir = projectDir;
-        this.dir = join(projectDir, '.memory');
+    /**
+     * The parsed log, together with the file identity it was parsed from.
+     *
+     * This is not the cache the module comment warns about. That one was rejected because
+     * it would let one process's view of history outlive the events that contradict it;
+     * this one is revalidated against the file's own size and mtime on every read, so an
+     * append by another process is seen on the next call exactly as before. What it avoids
+     * is re-parsing an unchanged file — the same log is folded several times inside one
+     * pre-step, and parsing it once per fold is the only part of that which is avoidable.
+     */
+    cached;
+    /** @param dir - the `.memory` directory itself, already resolved for its scope. */
+    constructor(dir) {
+        this.dir = dir;
         this.logPath = join(this.dir, 'events.jsonl');
     }
     get path() {
         return this.logPath;
     }
+    /**
+     * An identity for the file as it is right now, or null when there is no file.
+     *
+     * Size alone would miss a rewrite; mtime alone is too coarse on some Windows
+     * filesystems. Together they change on every append this process or another makes.
+     * `stat` costs a syscall; reading and parsing the file costs a syscall plus an
+     * allocation plus a JSON.parse per line, which is why this is worth doing.
+     */
+    signature() {
+        try {
+            const stats = statSync(this.logPath);
+            return `${stats.size}:${stats.mtimeMs}`;
+        }
+        catch {
+            return null;
+        }
+    }
     append(event) {
         if (!existsSync(this.dir))
             mkdirSync(this.dir, { recursive: true });
         // One `write` of one line: a crash can truncate the final line, but cannot interleave.
         appendFileSync(this.logPath, `${JSON.stringify(event)}\n`, 'utf8');
+        // Not strictly needed — the next `signature()` no longer matches — but it keeps the
+        // cached array from being handed out after this process has moved the log on.
+        this.cached = undefined;
     }
     /**
      * Read the whole log.
@@ -37,10 +67,18 @@ export class MemoryStore {
      * recoverable loss for a total one — so a torn *final* line is dropped. Corruption
      * anywhere else is a real problem and is reported rather than skipped, because
      * silently ignoring a damaged record is how a log stops being evidence.
+     *
+     * The returned array is shared with the cache: treat it as read-only.
      */
     readAll() {
-        if (!existsSync(this.logPath))
-            return [];
+        const key = this.signature();
+        if (this.cached !== undefined && this.cached.key === key)
+            return this.cached.events;
+        const events = key === null ? [] : this.parse();
+        this.cached = { key, events };
+        return events;
+    }
+    parse() {
         const lines = readFileSync(this.logPath, 'utf8').split('\n');
         const events = [];
         for (let index = 0; index < lines.length; index += 1) {

package/lib/tools.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Model-facing tools: the pull half of memory.
+ *
+ * Recall injection pushes what the plugin thinks is relevant. That is one direction only,
+ * and it leaves the model unable to ask the question it most often needs answered:
+ * "what did we already decide about this?" This module registers that question as two
+ * tools, so memory is something the model can consult rather than only something that
+ * arrives unasked.
+ *
+ * The two directions deliberately answer differently. The push path may only offer
+ * guidance — active and not contradicted — because unsolicited text influences the turn.
+ * The pull path is answering a question someone actually asked, so it can widen to
+ * contradicted or superseded records when asked to by name. The difference is carried by
+ * the `include` argument rather than by a second implementation, and `guidance` is still
+ * the default: a model that does not think about populations gets the same conservatism
+ * the push path applies.
+ *
+ * @module context-memory/tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ContextMemory } from './memory.js';
+/** How this plugin finds the log belonging to one call's recording context. */
+export interface MemoryToolOptions {
+    /**
+     * The instance for the session that issued the call.
+     *
+     * A tool call belongs to an agent, and an agent belongs to a session with its own
+     * working directory — which may not be the project the last pre-step resolved. Reading
+     * the shared "current" instance instead would answer a question about one project with
+     * another project's log.
+     */
+    resolve(agent: Agent | undefined, signal: AbortSignal): Promise<ContextMemory>;
+}
+/**
+ * Register both tools, once the host's tool registry exists.
+ *
+ * Registered through `ctx.inject` rather than a static `inject` entry for the same reason
+ * the working directory is read through `ctx.get`: this plugin must keep working on a host
+ * that mounts no tool registry (the CLI, a headless profile without tools), and a declared
+ * dependency on `tools` would leave the whole plugin pending — including the pre-step
+ * injection and the panel — on such a host. The tools are an addition, not a precondition.
+ */
+export declare function registerMemoryTools(ctx: Context, options: MemoryToolOptions): void;