dsh-context-memory 0.1.0

package/lib/identity.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Memory identity.
+ *
+ * Ids are derived from the normalised subject rather than assigned, so remembering the
+ * same thing twice folds into one memory instead of accumulating near-duplicates. A
+ * counter-based id would make every repeat a new record, and the panel would fill with
+ * the same fact in five slightly different phrasings.
+ *
+ * The subject is also what conflicts are decided on, which is why it is normalised here
+ * once and shown everywhere it is used — a conflict the user cannot see the basis of is
+ * not actionable.
+ *
+ * @module context-memory/identity
+ */
+/**
+ * Reduce a memory to the key it is stored and compared under.
+ *
+ * Lowercased, punctuation-stripped, whitespace-collapsed, and with a leading article
+ * dropped, so "The build uses pnpm" and "build uses pnpm" are the same memory. Filler
+ * that varies in wording but not meaning — "always", "never", "please" — is stripped
+ * too: those words change how a memory is checked, not what it is about, and keeping
+ * them would make the same fact conflict with itself.
+ */
+export declare function normaliseSubject(text: string): string;
+/**
+ * A stable short id for a memory, derived from its subject *and* its text.
+ *
+ * Both parts are hashed, which is what makes conflict detection possible at all. Keying
+ * on the text alone would give two disagreeing statements about one subject two
+ * unrelated ids, so nothing could tell they were about the same thing; keying on the
+ * subject alone would make the second statement fold into the first and silently
+ * overwrite it. Hashing the pair keeps the two cases distinct: the same statement
+ * repeated folds into one memory, while a different statement about the same subject
+ * stays separate and is reported as a conflict.
+ */
+export declare function memoryId(subject: string, text: string): string;

package/lib/identity.js

@@ -0,0 +1,56 @@
+/**
+ * Memory identity.
+ *
+ * Ids are derived from the normalised subject rather than assigned, so remembering the
+ * same thing twice folds into one memory instead of accumulating near-duplicates. A
+ * counter-based id would make every repeat a new record, and the panel would fill with
+ * the same fact in five slightly different phrasings.
+ *
+ * The subject is also what conflicts are decided on, which is why it is normalised here
+ * once and shown everywhere it is used — a conflict the user cannot see the basis of is
+ * not actionable.
+ *
+ * @module context-memory/identity
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Reduce a memory to the key it is stored and compared under.
+ *
+ * Lowercased, punctuation-stripped, whitespace-collapsed, and with a leading article
+ * dropped, so "The build uses pnpm" and "build uses pnpm" are the same memory. Filler
+ * that varies in wording but not meaning — "always", "never", "please" — is stripped
+ * too: those words change how a memory is checked, not what it is about, and keeping
+ * them would make the same fact conflict with itself.
+ */
+export function normaliseSubject(text) {
+    const stripped = text
+        .toLowerCase()
+        .replace(/[`"'.,;:!?()[\]]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .replace(/^(?:always|never|please|note that|remember that|the)\s+/i, '')
+        .trim();
+    // Applied repeatedly: fillers stack ("please note that the build uses pnpm"), and a
+    // single pass would leave "note that …" behind, so the same fact said politely and
+    // said plainly would be two subjects instead of one.
+    let result = stripped;
+    let previous;
+    do {
+        previous = result;
+        result = result.replace(/^(?:always|never|please|note that|remember that|the)\s+/i, '');
+    } while (result !== previous);
+    return result;
+}
+/**
+ * A stable short id for a memory, derived from its subject *and* its text.
+ *
+ * Both parts are hashed, which is what makes conflict detection possible at all. Keying
+ * on the text alone would give two disagreeing statements about one subject two
+ * unrelated ids, so nothing could tell they were about the same thing; keying on the
+ * subject alone would make the second statement fold into the first and silently
+ * overwrite it. Hashing the pair keeps the two cases distinct: the same statement
+ * repeated folds into one memory, while a different statement about the same subject
+ * stays separate and is reported as a conflict.
+ */
+export function memoryId(subject, text) {
+    return createHash('sha256').update(`${subject}\u0000${normaliseSubject(text)}`).digest('hex').slice(0, 12);
+}

package/lib/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Host half of dsh-context-memory.
+ *
+ * `apply` is the only entry point the loader calls, and everything the plugin does
+ * happens here rather than at install time — dsh rejects plugins whose dependencies
+ * carry install lifecycle scripts, so there is no `prepare` step to hide behind.
+ *
+ * @module context-memory/index
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { ContextMemory, type RememberInput } from './memory.js';
+import type { MemoryKind, MemorySource, PanelPayload, RecallHit, VerifySummary } from './types.js';
+export declare const name = "dsh-context-memory";
+/** The service shape other plugins and the panel use. */
+export interface MemoryService {
+    remember(input: RememberInput): ReturnType<ContextMemory['remember']>;
+    forget(id: string, reason: string, replacedBy?: string): boolean;
+    recall(query: string, limit?: number): RecallHit[];
+    conflicts(): ReturnType<ContextMemory['conflicts']>;
+    verify(): VerifySummary;
+    active(): ReturnType<ContextMemory['active']>;
+    panel(): PanelPayload;
+}
+export declare function apply(ctx: Context): void;
+export type { MemoryKind, MemorySource };

package/lib/index.js

@@ -0,0 +1,28 @@
+/**
+ * Host half of dsh-context-memory.
+ *
+ * `apply` is the only entry point the loader calls, and everything the plugin does
+ * happens here rather than at install time — dsh rejects plugins whose dependencies
+ * carry install lifecycle scripts, so there is no `prepare` step to hide behind.
+ *
+ * @module context-memory/index
+ */
+import { resolve } from 'node:path';
+import { ContextMemory } from './memory.js';
+import { registerMemoryRoutes } from './routes.js';
+export const name = 'dsh-context-memory';
+export function apply(ctx) {
+    const root = resolve(process.cwd());
+    const memory = new ContextMemory(root);
+    const service = {
+        remember: (input) => memory.remember(input),
+        forget: (id, reason, replacedBy) => memory.forget(id, reason, replacedBy),
+        recall: (query, limit) => memory.recall(query, limit),
+        conflicts: () => memory.conflicts(),
+        verify: () => memory.verify(),
+        active: () => memory.active(),
+        panel: () => memory.panel(),
+    };
+    ctx.provide('contextMemory', service);
+    registerMemoryRoutes(ctx, service);
+}

package/lib/memory.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The memory service.
+ *
+ * Current state is always a fold over the event log, recomputed rather than cached.
+ * That is the point of the plugin: two processes reading the same log must agree on
+ * what is remembered, and a cache would let one process's view of history outlive the
+ * events that contradict it.
+ *
+ * @module context-memory/memory
+ */
+import type { Conflict, Memory, MemoryKind, MemorySource, MemoryState, PanelPayload, RecallHit, VerifySummary } from './types.js';
+export interface RememberInput {
+    text: string;
+    /**
+     * What the memory is about. Defaults to the statement itself, so repeats fold; supply
+     * it to make two different statements about one thing reportable as a conflict.
+     */
+    subject?: string;
+    kind?: MemoryKind;
+    source?: MemorySource;
+    sessionId?: string;
+    step?: number;
+}
+export declare class ContextMemory {
+    private readonly projectDir;
+    private readonly store;
+    constructor(projectDir: string);
+    get logPath(): string;
+    /**
+     * Fold the log into current state.
+     *
+     * Events are applied in log order and a memory is always addressable by id, so a
+     * supersede or verify that names a memory not yet seen is skipped rather than
+     * creating a phantom entry — a log that lost its `remember` line must not resurrect
+     * the memory from its consequences.
+     */
+    all(): MemoryState[];
+    active(): MemoryState[];
+    get(id: string): MemoryState | undefined;
+    /**
+     * Record a memory.
+     *
+     * The id is derived from the subject and the text, so remembering the same statement
+     * again refreshes its guard rather than creating a second copy — but it does not
+     * silently supersede it either. Re-remembering is not evidence that the old statement
+     * became wrong; only an explicit supersede says that. Two *different* statements about
+     * the same subject stay separate, and `conflicts` reports them together.
+     *
+     * A guard is compiled only from the statement's own text. Whatever the caller passes
+     * is never executed: memories can be written by the agent, so a memory-supplied
+     * command would be an injection path.
+     */
+    remember(input: RememberInput, now?: number): Memory;
+    /**
+     * Retire a memory, with a reason.
+     *
+     * Deletion is not offered. A memory that turns out to be wrong is the most valuable
+     * record in the log — it is the only thing that can explain a past decision — so it is
+     * marked superseded and kept, and the reason is required because "why did this stop
+     * being true" is the question that will be asked later.
+     */
+    forget(id: string, reason: string, replacedBy?: string, now?: number): boolean;
+    /**
+     * Group active memories that share a subject but say different things.
+     *
+     * The plugin deliberately does not pick a winner. Two memories with the same subject
+     * and different text means one of them is wrong and the log does not say which; a
+     * plausible-looking choice would be exactly the unfounded assertion this plugin exists
+     * to eliminate.
+     */
+    conflicts(): Conflict[];
+    /** Rank active memories against a query. */
+    recall(query: string, limit?: number, now?: number): RecallHit[];
+    /**
+     * Re-run every compiled guard.
+     *
+     * Keys accumulate because they are not interchangeable: `violated` is the world
+     * disagreeing with a memory, `broken` is the check itself being unusable, and
+     * `uncheckable` is there being no check. Only the first is evidence about the memory,
+     * so only the first may influence a caller's exit code.
+     */
+    verify(now?: number): VerifySummary;
+    /**
+     * The exit code a caller should use.
+     *
+     * Only a rule the world actually contradicted makes this non-zero. A guard that could
+     * not run is a defect in the check, not in the memory, and letting it turn a pipeline
+     * red is how a typo would get a true memory marked false.
+     */
+    static exitCode(summary: VerifySummary): number;
+    panel(): PanelPayload;
+}

package/lib/memory.js

@@ -0,0 +1,200 @@
+/**
+ * The memory service.
+ *
+ * Current state is always a fold over the event log, recomputed rather than cached.
+ * That is the point of the plugin: two processes reading the same log must agree on
+ * what is remembered, and a cache would let one process's view of history outlive the
+ * events that contradict it.
+ *
+ * @module context-memory/memory
+ */
+import { compileGuard, runGuard } from './guard.js';
+import { memoryId, normaliseSubject } from './identity.js';
+import { recall as rankRecall } from './recall.js';
+import { MemoryStore } from './store.js';
+export class ContextMemory {
+    projectDir;
+    store;
+    constructor(projectDir) {
+        this.projectDir = projectDir;
+        this.store = new MemoryStore(projectDir);
+    }
+    get logPath() {
+        return this.store.path;
+    }
+    /**
+     * Fold the log into current state.
+     *
+     * Events are applied in log order and a memory is always addressable by id, so a
+     * supersede or verify that names a memory not yet seen is skipped rather than
+     * creating a phantom entry — a log that lost its `remember` line must not resurrect
+     * the memory from its consequences.
+     */
+    all() {
+        const byId = new Map();
+        for (const event of this.store.readAll()) {
+            if (event.type === 'remember') {
+                byId.set(event.memory.id, { ...event.memory, status: 'active' });
+                continue;
+            }
+            const target = byId.get(event.id);
+            if (!target)
+                continue;
+            if (event.type === 'supersede') {
+                target.status = 'superseded';
+                target.supersededReason = event.reason;
+                if (event.replacedBy !== undefined)
+                    target.supersededBy = event.replacedBy;
+                continue;
+            }
+            target.verification = { at: event.at, outcome: event.outcome, exitCode: event.exitCode, output: event.output };
+        }
+        return [...byId.values()].sort((a, b) => b.createdAt - a.createdAt);
+    }
+    active() {
+        return this.all().filter((memory) => memory.status === 'active');
+    }
+    get(id) {
+        return this.all().find((memory) => memory.id === id);
+    }
+    /**
+     * Record a memory.
+     *
+     * The id is derived from the subject and the text, so remembering the same statement
+     * again refreshes its guard rather than creating a second copy — but it does not
+     * silently supersede it either. Re-remembering is not evidence that the old statement
+     * became wrong; only an explicit supersede says that. Two *different* statements about
+     * the same subject stay separate, and `conflicts` reports them together.
+     *
+     * A guard is compiled only from the statement's own text. Whatever the caller passes
+     * is never executed: memories can be written by the agent, so a memory-supplied
+     * command would be an injection path.
+     */
+    remember(input, now = Date.now()) {
+        const text = input.text.trim();
+        if (text.length === 0)
+            throw new Error('cannot remember an empty statement');
+        const subject = input.subject !== undefined && input.subject.trim().length > 0
+            ? normaliseSubject(input.subject)
+            : normaliseSubject(text);
+        const id = memoryId(subject, text);
+        const guard = compileGuard(text);
+        const memory = { id, subject, text, kind: input.kind ?? 'fact', source: input.source ?? 'user', createdAt: now };
+        if (input.sessionId !== undefined)
+            memory.sessionId = input.sessionId;
+        if (input.step !== undefined)
+            memory.step = input.step;
+        if (guard)
+            memory.guard = guard;
+        const existing = this.get(id);
+        // Keep the original creation time: re-stating a memory is not the memory being new,
+        // and resetting it would let any repeat silently outrank older, better-evidenced ones.
+        if (existing)
+            memory.createdAt = existing.createdAt;
+        this.store.append({ type: 'remember', at: now, memory });
+        return memory;
+    }
+    /**
+     * Retire a memory, with a reason.
+     *
+     * Deletion is not offered. A memory that turns out to be wrong is the most valuable
+     * record in the log — it is the only thing that can explain a past decision — so it is
+     * marked superseded and kept, and the reason is required because "why did this stop
+     * being true" is the question that will be asked later.
+     */
+    forget(id, reason, replacedBy, now = Date.now()) {
+        if (!this.get(id))
+            return false;
+        if (reason.trim().length === 0)
+            throw new Error('a memory can only be superseded with a reason');
+        const event = { type: 'supersede', at: now, id, reason: reason.trim() };
+        if (replacedBy !== undefined)
+            event.replacedBy = replacedBy;
+        this.store.append(event);
+        return true;
+    }
+    /**
+     * Group active memories that share a subject but say different things.
+     *
+     * The plugin deliberately does not pick a winner. Two memories with the same subject
+     * and different text means one of them is wrong and the log does not say which; a
+     * plausible-looking choice would be exactly the unfounded assertion this plugin exists
+     * to eliminate.
+     */
+    conflicts() {
+        const groups = new Map();
+        for (const memory of this.active()) {
+            const group = groups.get(memory.subject);
+            if (group)
+                group.push(memory);
+            else
+                groups.set(memory.subject, [memory]);
+        }
+        const conflicts = [];
+        for (const [subject, memories] of groups) {
+            if (memories.length > 1)
+                conflicts.push({ subject, memories });
+        }
+        return conflicts.sort((a, b) => b.memories.length - a.memories.length);
+    }
+    /** Rank active memories against a query. */
+    recall(query, limit = 5, now = Date.now()) {
+        return rankRecall(this.all(), query, limit, now);
+    }
+    /**
+     * Re-run every compiled guard.
+     *
+     * Keys accumulate because they are not interchangeable: `violated` is the world
+     * disagreeing with a memory, `broken` is the check itself being unusable, and
+     * `uncheckable` is there being no check. Only the first is evidence about the memory,
+     * so only the first may influence a caller's exit code.
+     */
+    verify(now = Date.now()) {
+        const summary = { passed: 0, violated: 0, broken: 0, uncheckable: 0, results: [] };
+        for (const memory of this.active()) {
+            if (!memory.guard) {
+                summary.uncheckable += 1;
+                summary.results.push({ id: memory.id, text: memory.text, outcome: 'uncheckable', exitCode: null, output: '' });
+                continue;
+            }
+            const run = runGuard(memory.id, memory.guard, this.projectDir, new Date(now));
+            this.store.append({ type: 'verify', at: now, id: memory.id, outcome: run.outcome, exitCode: run.exitCode, output: run.output });
+            const result = { id: memory.id, text: memory.text, outcome: run.outcome, exitCode: run.exitCode, output: run.output };
+            summary.results.push(result);
+            if (run.outcome === 'passed')
+                summary.passed += 1;
+            else if (run.outcome === 'violated')
+                summary.violated += 1;
+            else
+                summary.broken += 1;
+        }
+        return summary;
+    }
+    /**
+     * The exit code a caller should use.
+     *
+     * Only a rule the world actually contradicted makes this non-zero. A guard that could
+     * not run is a defect in the check, not in the memory, and letting it turn a pipeline
+     * red is how a typo would get a true memory marked false.
+     */
+    static exitCode(summary) {
+        return summary.violated > 0 ? 1 : 0;
+    }
+    panel() {
+        const all = this.all();
+        const active = all.filter((memory) => memory.status === 'active');
+        const superseded = all.filter((memory) => memory.status === 'superseded');
+        return {
+            active,
+            superseded,
+            conflicts: this.conflicts(),
+            totals: {
+                active: active.length,
+                superseded: superseded.length,
+                withGuard: active.filter((memory) => memory.guard).length,
+                verified: active.filter((memory) => memory.verification?.outcome === 'passed').length,
+                unverified: active.filter((memory) => memory.verification?.outcome !== 'passed').length,
+            },
+        };
+    }
+}

package/lib/memory.web.js

@@ -0,0 +1,60 @@
+// src/client/view.tsx
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function verificationLabel(memory) {
+  if (!memory.guard) return "no check";
+  switch (memory.verification?.outcome) {
+    case "passed":
+      return "checked, holds";
+    case "violated":
+      return "checked, does not hold";
+    case "broken":
+      return "check unusable";
+    default:
+      return "not yet checked";
+  }
+}
+function rows(memories) {
+  return memories.map((memory) => {
+    const provenance = [
+      memory.source,
+      memory.sessionId ? `session ${memory.sessionId}` : null,
+      memory.step !== void 0 ? `step ${memory.step}` : null
+    ].filter(Boolean).join(" \xB7 ");
+    return `<tr><td><code>${escapeHtml(memory.id)}</code></td><td>${escapeHtml(memory.text)}</td><td>${escapeHtml(memory.kind)}</td><td>${escapeHtml(verificationLabel(memory))}</td><td>${escapeHtml(provenance)}</td></tr>`;
+  }).join("");
+}
+function renderPanel(payload) {
+  const { totals } = payload;
+  const summary = `<p class="memory-summary">${totals.active} active (${totals.verified} checked and holding, ${totals.unverified} not), ${totals.superseded} superseded, ${totals.withGuard} with a compiled check.</p>`;
+  const conflictBlock = payload.conflicts.length === 0 ? "<p>No conflicts.</p>" : `<div class="memory-conflicts"><h3>Conflicts</h3><ul>${payload.conflicts.map((conflict) => `<li><strong>${escapeHtml(conflict.subject)}</strong><ul>${conflict.memories.map((memory) => `<li><code>${escapeHtml(memory.id)}</code> ${escapeHtml(memory.text)}</li>`).join("")}</ul></li>`).join("")}</ul></div>`;
+  const activeBlock = payload.active.length === 0 ? "<p>Nothing is remembered yet.</p>" : `<table><thead><tr><th>Id</th><th>Memory</th><th>Kind</th><th>Status</th><th>From</th></tr></thead><tbody>${rows(payload.active)}</tbody></table>`;
+  const supersededBlock = payload.superseded.length === 0 ? "" : `<details><summary>Superseded (${payload.superseded.length})</summary><table><thead><tr><th>Id</th><th>Memory</th><th>Kind</th><th>Status</th><th>From</th></tr></thead><tbody>${rows(payload.superseded)}</tbody></table></details>`;
+  return `<div class="context-memory-panel"><h2>Context memory</h2>${summary}${conflictBlock}<h3>Active</h3>${activeBlock}${supersededBlock}</div>`;
+}
+
+// src/client/index.tsx
+var inject = ["@deepseek-ai/dsh-client-ui-settings", "@deepseek-ai/dsh-client-connection"];
+function apply(ctx) {
+  ctx.inject(inject, (settings, connection) => {
+    const s = settings;
+    const c = connection;
+    s.section("context-memory", {
+      title: "Context memory",
+      render: async () => {
+        try {
+          const res = await c.fetch("/api/context-memory.panel");
+          const payload = await res.json();
+          return renderPanel(payload);
+        } catch (error) {
+          return `<div class="context-memory-panel"><h2>Context memory</h2><p>Could not load memories: ${String(error)}</p></div>`;
+        }
+      }
+    });
+  });
+}
+export {
+  apply,
+  inject
+};

package/lib/recall.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Recall: which memories are relevant to a query.
+ *
+ * The alternative to ranking is pasting every stored memory into the context window,
+ * which costs tokens on every turn and buries the one that mattered. So retrieval is
+ * scored, and the score is broken down into named parts that are returned alongside the
+ * result — a ranking the user cannot inspect is a ranking they have to trust.
+ *
+ * Verification strength is part of the score, not a separate display concern: a memory
+ * that was checked against the world is worth more than one that was merely stated, and
+ * encoding that in one number is what makes "recall the most reliable thing you know"
+ * expressible at all.
+ *
+ * @module context-memory/recall
+ */
+import type { MemoryState, RecallHit } from './types.js';
+/** Split a query into distinct signal-bearing tokens. */
+export declare function tokenize(text: string): string[];
+/**
+ * Score how relevant one memory is to a query.
+ *
+ * Overlap dominates because it is the only part grounded in the query. Recency is a
+ * tiebreaker, not a signal: a three-year-old decision that matches the query beats a
+ * fresh memory that does not. Verification credit is all-or-nothing — a memory either
+ * passed a check or it did not, and giving partial credit for "was checked once and has
+ * not been rechecked" would reward staleness.
+ */
+export declare function scoreMemory(memory: MemoryState, tokens: string[], now?: number): {
+    score: number;
+    matched: string[];
+    why: string;
+};
+/**
+ * Rank active memories against a query.
+ *
+ * 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.
+ */
+export declare function recall(memories: MemoryState[], query: string, limit?: number, now?: number): RecallHit[];

package/lib/recall.js

@@ -0,0 +1,77 @@
+/**
+ * Recall: which memories are relevant to a query.
+ *
+ * The alternative to ranking is pasting every stored memory into the context window,
+ * which costs tokens on every turn and buries the one that mattered. So retrieval is
+ * scored, and the score is broken down into named parts that are returned alongside the
+ * result — a ranking the user cannot inspect is a ranking they have to trust.
+ *
+ * Verification strength is part of the score, not a separate display concern: a memory
+ * that was checked against the world is worth more than one that was merely stated, and
+ * encoding that in one number is what makes "recall the most reliable thing you know"
+ * expressible at all.
+ *
+ * @module context-memory/recall
+ */
+import { normaliseSubject } from './identity.js';
+/** Words that carry no retrieval signal and would match almost any memory. */
+const STOP_WORDS = new Set([
+    'a', 'an', 'and', 'are', 'as', 'at', 'be', 'but', 'by', 'do', 'does', 'for', 'from',
+    'has', 'have', 'how', 'i', 'in', 'is', 'it', 'its', 'of', 'on', 'or', 'that', 'the',
+    '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. */
+export function tokenize(text) {
+    const seen = new Set();
+    for (const raw of text.toLowerCase().split(/[^a-z0-9_.-]+/)) {
+        if (raw.length < 2 || STOP_WORDS.has(raw))
+            continue;
+        seen.add(raw);
+    }
+    return [...seen];
+}
+/** How much each part of the score can contribute. Sums to 1. */
+const WEIGHTS = {
+    overlap: 0.6,
+    recency: 0.2,
+    verification: 0.2,
+};
+/** A memory older than this contributes no recency credit. */
+const RECENCY_HORIZON_MS = 90 * 24 * 60 * 60 * 1000;
+/**
+ * Score how relevant one memory is to a query.
+ *
+ * Overlap dominates because it is the only part grounded in the query. Recency is a
+ * tiebreaker, not a signal: a three-year-old decision that matches the query beats a
+ * fresh memory that does not. Verification credit is all-or-nothing — a memory either
+ * 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}`);
+    const matched = tokens.filter((token) => subject.includes(token));
+    const overlap = tokens.length === 0 ? 0 : matched.length / tokens.length;
+    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'}`;
+    return { score, matched, why };
+}
+/**
+ * Rank active memories against a query.
+ *
+ * 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.
+ */
+export function recall(memories, query, limit = 5, now = Date.now()) {
+    const tokens = tokenize(query);
+    return memories
+        .filter((memory) => memory.status === 'active')
+        .map((memory) => ({ memory, ...scoreMemory(memory, tokens, now) }))
+        .filter((hit) => hit.matched.length > 0)
+        .sort((a, b) => b.score - a.score || b.memory.createdAt - a.memory.createdAt)
+        .slice(0, limit);
+}

package/lib/routes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Host routes for the panel.
+ *
+ * Registered on the host's web connection when one exists. A host running headless
+ * simply skips registration and every other part of the plugin keeps working — the
+ * panel is a view of the log, not a precondition for keeping it.
+ *
+ * @module context-memory/routes
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryService } from './index.js';
+/** The panel path, shared with the browser half so the two cannot drift apart. */
+export declare const MEMORY_PANEL_PATH = "/api/context-memory.panel";
+export declare function registerMemoryRoutes(ctx: Context, memory: MemoryService): void;