@chatpanel/gateway 0.6.43 → 0.6.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.43",
+  "version": "0.6.45",
   "description": "Local privacy gateway \u2014 redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {

package/src/mcp.js

@@ -17,6 +17,7 @@
 import { loadConfig } from './config.js';
 import { readBridgeToken } from './bridge.js';
 import { ensureGatewayToken } from './gateway-token.js';
+import { MEMORY_KINDS, MEMORY_KIND_NAMES } from './memory.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER = { name: 'chatpanel-history', version: '1.0.0' };
@@ -33,12 +34,24 @@ const INSTRUCTIONS = [
   'meeting, call, demo, note, or past conversation ("outcome of the meeting", "what did we',
   'decide", "action items", "notes from yesterday", a person/day/topic in their history),',
   'ALSO consult ChatPanel — it is the source of truth for that personal history:',
-  '  • search_history — search by CONTENT (not the generic meeting title). Supports filters:',
+  '  • smart_search — START HERE: give it the question plus 2-4 of your own keyword',
+  '    phrasings; it runs them all and fuses the rankings, finding what one query misses.',
+  '  • search_history — one exact keyword query, when you already know the terms. Search by',
+  '    CONTENT (not the generic meeting title). Supports filters:',
   '    type (chat|meeting|note), since/before (dates or relative like "7d", "yesterday"),',
   '    and limit/offset paging. Returns compact snippets, not full bodies.',
   '  • get_record — the full text of one result id; use maxChars/offset to page a long',
   '    transcript instead of pulling it all into context.',
   '  • find_related — follow the graph: given a record id, the records most connected to it.',
+  '',
+  'ChatPanel also holds the user\'s MEMORY — a short list of durable facts about them (their',
+  'name, how they want answers written, what they are working on) that applies to EVERY task,',
+  'not just ones about their history:',
+  '  • recall — call it EARLY in a session, and whenever the user states a preference, to see',
+  '    what is already known. Then simply follow it; do not tell them you looked.',
+  '  • remember — save a new durable fact when they state one ("call me Alex", "always use',
+  '    pnpm"). One short sentence. Not for task details or anything true only today.',
+  '  • forget — remove one when they say it no longer holds.',
   'Prefer these for the user\'s history and combine them with your other tools as you see fit.',
   'Every result states how fresh the local copy is; if something recent is missing it may not',
   'have synced yet — say so rather than concluding it does not exist.',
@@ -103,6 +116,22 @@ async function bridgeJson(path) {
 }
 
 const TOOLS = [
+  {
+    name: 'smart_search',
+    description: 'BEST first choice for a question about the user\'s ChatPanel history (meetings, notes, past chats). Ask it a natural-language QUESTION and it expands that into several complementary keyword queries, runs them all, and fuses the rankings — which finds things a single query misses, in one round trip instead of several probes. You know the domain, so pass 2-4 of your own phrasings in `queries` too (e.g. for "what did we decide in the Ben demo": ["Ben demo decisions", "tooling demo action items", "demo outcome next steps"]). Supports the same filters as search_history (type, since, before) and returns snippets with each result\'s id; follow up with get_record for the full text or find_related to expand around a hit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        question: { type: 'string', description: 'The user\'s question, in natural language.' },
+        queries: { type: 'array', items: { type: 'string' }, description: 'Your own 2-4 keyword formulations of it — these lead the search.' },
+        type: { type: 'string', enum: ['chat', 'meeting', 'note'], description: 'Only this kind of record.' },
+        since: { type: 'string', description: 'Earliest date: 2026-08-01, or a window like "7d"/"yesterday".' },
+        before: { type: 'string', description: 'Latest date: a date or window like `since`.' },
+        limit: { type: 'number', description: 'Max fused results (default 10).' },
+      },
+      required: ['question'],
+    },
+  },
   {
     name: 'search_history',
     description: 'Search the user\'s ChatPanel history — their past chats, meeting/call transcripts, and notes — by keyword relevance. Consult this (in ADDITION to your other tools) whenever the question touches a meeting, call, demo, note, or past conversation: "outcome of the meeting", "what did we decide", "action items", "what did <person> say", "notes from yesterday". Filters: `type` (chat|meeting|note), `since`/`before` (a date like 2026-08-01 or a relative window like "7d"/"yesterday"), and `limit`/`offset` for paging. Returns compact SNIPPETS (the matching excerpt) with each record\'s id/title/type/date — token-friendly; call get_record for the full text and find_related to follow connections. This is a LOCAL WARM COPY that syncs from ChatPanel; very recent items may not be here yet — results report how current the index is, so if something is missing it likely has not synced. Meeting titles are often generic ("Zoom Meeting"), so search by CONTENT, not the title.',
@@ -155,6 +184,38 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'recall',
+    description: "What ChatPanel already knows about the USER — their name, how they want answers written, their ongoing work and environment. Short and cheap; call it at the START of a session and whenever the user states a preference, then just FOLLOW what it returns without announcing that you checked. Pass the current task in `text` and it also returns the facts relevant to that task, not only the always-on ones. This is memory, not history: for what was said in a meeting or a past chat use smart_search instead.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'What the user is asking about right now, so task-relevant facts come back too. Omit for just the always-on ones.' },
+      },
+    },
+  },
+  {
+    name: 'remember',
+    description: "Save a durable fact about the USER to ChatPanel, carried into every future session on every model and agent — the side panel, other CLIs, everything. Use it the moment they state a standing preference (\"always use pnpm\"), an identity fact (\"call me Alex\") or a constraint that will still be true next week. Do NOT use it for task details, anything obvious from the current work, or notes about a codebase — those belong in the repo. One short self-contained sentence, written in the third person. Saving is a change to the user's own data, so say in a short clause what you saved.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'The fact, one short sentence in the third person ("Prefers pnpm over npm"). Max 280 characters.' },
+        kind: { type: 'string', enum: MEMORY_KIND_NAMES, description: MEMORY_KIND_NAMES.map((k) => `${k}: ${MEMORY_KINDS[k].hint}`).join(' ') },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Optional short tags for grouping.' },
+      },
+      required: ['text'],
+    },
+  },
+  {
+    name: 'forget',
+    description: 'Remove a memory from ChatPanel when the user says it no longer holds. Name it however they did ("the Frankfurt thing") or pass the id from recall — it matches on meaning, and tells you exactly what it removed.',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'The memory to remove: its text, roughly how the user named it, or its id.' } },
+      required: ['query'],
+    },
+  },
   {
     name: 'list_skills',
     description: 'List the reusable skills installed on this machine (via the ChatPanel bridge) — across every agent harness (Claude Code, Codex, Copilot, Gemini, Hermes) and any configured folder. Returns each skill\'s name and one-line description. Call open_skill to load the one that fits the task.',
@@ -192,6 +253,16 @@ function horizonLine(newest, size) {
   return `Index: ${size} records, current through ${iso} (local warm copy — items newer than this may not have synced from ChatPanel yet).`;
 }
 
+// Memory WRITES are admin-gated on the gateway (a drive-by localhost page must not be able to
+// install a standing instruction), so they carry the gateway token — readable only by this
+// same-user process. Reads need none: an open warm index is the product.
+function writeAuth() {
+  try {
+    const token = ensureGatewayToken();
+    return token ? { Authorization: `Bearer ${token}` } : {};
+  } catch { return {}; }
+}
+
 async function gatewayJson(path, init) {
   let res;
   try {
@@ -230,6 +301,30 @@ function parseWhen(v) {
 const fmtRow = (r, i) => `${i + 1}. [${r.id}] ${r.title || '(untitled)'} · ${r.type}${r.date ? ' · ' + new Date(r.date).toISOString().slice(0, 10) : ''}${r.snippet ? `\n     ${r.snippet}` : ''}`;
 
 async function callTool(name, args = {}) {
+  if (name === 'smart_search') {
+    const body = {
+      question: String(args.question || ''),
+      queries: Array.isArray(args.queries) ? args.queries.map(String) : [],
+      limit: Number(args.limit) || 10,
+    };
+    if (args.type) body.type = String(args.type);
+    const since = parseWhen(args.since); if (since != null) body.since = since;
+    const before = parseWhen(args.before); if (before != null) body.before = before;
+    const data = await gatewayJson('/v1/history/smart-search', {
+      method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),
+    });
+    const rows = data.results || [];
+    const horizon = horizonLine(data.newest, data.size);
+    const asked = (data.queries || []).map((q) => `"${q}"`).join(', ');
+    if (!rows.length) {
+      return `No match for "${args.question}".\nSearched ${data.queries?.length || 0} way(s): ${asked}.\n${horizon}\nIf you expected a recent item it may not have synced yet — check ChatPanel directly, or try different keywords (meeting titles are often generic).`;
+    }
+    return [
+      horizon, '',
+      `${rows.length} result(s) for "${args.question}" — searched ${data.queries.length} way(s): ${asked}`,
+      ...rows.map((r, i) => `${fmtRow(r, i)}${r.foundBy?.length > 1 ? `\n     (matched ${r.foundBy.length} of the queries)` : ''}`),
+    ].join('\n') + '\n\nget_record <id> for full text (maxChars/offset to page) · find_related <id> to follow connections.';
+  }
   if (name === 'search_history') {
     const body = { query: String(args.query || ''), limit: Number(args.limit) || 10, offset: Math.max(0, Number(args.offset) || 0) };
     if (args.type) body.type = String(args.type);
@@ -272,6 +367,49 @@ async function callTool(name, args = {}) {
     const newest = items[0]?.date || null;
     return [horizonLine(newest, data.total), '', `${items.length} of ${data.total} records:`, ...items.map((it) => `[${it.id}] ${it.title || '(untitled)'} · ${it.type}${it.date ? ' · ' + new Date(it.date).toISOString().slice(0, 10) : ''} · ${it.chars} chars`)].join('\n');
   }
+  if (name === 'recall') {
+    const data = await gatewayJson('/v1/memory/recall', {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ text: String(args.text || '') }),
+    });
+    if (!data.memories?.length) {
+      return data.size
+        ? 'Nothing in ChatPanel memory applies here.'
+        : 'ChatPanel memory is empty — nothing is known about this user yet. Use `remember` when they state something durable about themselves or how they want to work.';
+    }
+    // The SHARED rendering, straight from the gateway, so a CLI agent is told exactly what
+    // the side panel's models are told. Two renderings would drift, invisibly.
+    return data.block;
+  }
+  if (name === 'remember') {
+    const text = String(args.text || '').trim();
+    if (!text) return 'remember needs `text` — one short sentence about the user.';
+    const data = await gatewayJson('/v1/memory/remember', {
+      method: 'POST', headers: { 'content-type': 'application/json', ...writeAuth() },
+      body: JSON.stringify({
+        text,
+        kind: args.kind ? String(args.kind) : 'fact',
+        tags: Array.isArray(args.tags) ? args.tags.map(String) : [],
+        // Attribution is the accountability here. A CLI has no confirm dialog to show, so
+        // instead every memory an agent writes is stamped with WHICH agent wrote it and
+        // shows up that way in the extension's Memory page, where the user can correct or
+        // delete it. Silent and anonymous would be the unacceptable combination.
+        source: { via: 'mcp', surface: 'mcp', agent: clientName },
+      }),
+    });
+    if (data.action === 'duplicate') return `Already known: "${data.record.text}" — nothing changed.`;
+    if (data.action === 'update') return `Updated memory to "${data.record.text}" (was "${data.replaced?.text}"). It applies to every future session.`;
+    return `Remembered: "${data.record.text}". It applies to every future ChatPanel session, on every model.`;
+  }
+  if (name === 'forget') {
+    const query = String(args.query || '').trim();
+    if (!query) return 'forget needs `query` — the memory to remove.';
+    const data = await gatewayJson('/v1/memory/forget', {
+      method: 'POST', headers: { 'content-type': 'application/json', ...writeAuth() }, body: JSON.stringify({ query }),
+    });
+    if (!data.removed?.length) return `No memory matches "${query}". Call recall to see what is stored.`;
+    return `Forgot: ${data.removed.map((m) => `"${m.text}"`).join(', ')}.`;
+  }
   if (name === 'list_skills') {
     let data;
     try { data = await bridgeJson('/skills'); }

package/src/memory-store.js

@@ -0,0 +1,176 @@
+// MEMORY on the gateway — the durable facts about the user, available to every local agent.
+//
+// The extension has its own copy in chrome.storage; this is the one CLI agents can reach.
+// Claude Code, Codex, OpenCode and anything else that speaks MCP get the user's standing
+// preferences through `chatpanel-gateway mcp`, so "call me Alex, never open with a preamble"
+// holds in the terminal exactly as it does in the side panel. That was the whole point of
+// putting memory in a shared contract rather than in the panel.
+//
+// TWO STORES, ONE TRUTH, because reconcile is idempotent. The extension pushes its memories
+// here and pulls back what the agents wrote (see the extension's warm-sync). A naive
+// two-way sync would duplicate on every pass; this one converges because `reconcile` keys on
+// the FACT (its slot, then its wording), not on a row id — so pushing the same memory twice
+// is a no-op and a corrected one supersedes rather than accumulating. The merge is the same
+// function on both sides, from the same file, which is the only reason that holds.
+//
+// ENCRYPTED AT REST with the same local key as the history store — this is the on-device
+// tier, and a local key is correct for it.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import os from 'node:os';
+import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+import {
+  normalizeMemory, reconcile, recall, memoryBlock, matchForForget, pruneMemories, markUsed,
+  isValidMemory, upcastMemory, DEFAULT_MAX_MEMORIES,
+} from './memory.js';
+
+const DIR = join(os.homedir(), '.chatpanel');
+const STORE_PATH = process.env.CHATPANEL_MEMORY_STORE || join(DIR, 'memory-store.enc');
+const KEY_PATH = process.env.CHATPANEL_HISTORY_KEY || join(DIR, 'history-key');
+
+const uid = () => `mem_${Date.now().toString(36)}${randomBytes(4).toString('hex')}`;
+
+// The same local key file the history store uses. One device key, not two: a second key file
+// is a second thing to lose, and both stores are the same tier with the same threat model.
+function loadOrCreateKey() {
+  try {
+    if (existsSync(KEY_PATH)) return Buffer.from(readFileSync(KEY_PATH, 'utf8').trim(), 'base64');
+  } catch { /* regenerate below */ }
+  const key = randomBytes(32);
+  mkdirSync(dirname(KEY_PATH), { recursive: true });
+  writeFileSync(KEY_PATH, key.toString('base64'), { mode: 0o600 });
+  return key;
+}
+
+function encrypt(key, buf) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ct = Buffer.concat([cipher.update(buf), cipher.final()]);
+  return { v: 1, iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), ct: ct.toString('base64') };
+}
+
+function decrypt(key, env) {
+  const d = createDecipheriv('aes-256-gcm', key, Buffer.from(env.iv, 'base64'));
+  d.setAuthTag(Buffer.from(env.tag, 'base64'));
+  return Buffer.concat([d.update(Buffer.from(env.ct, 'base64')), d.final()]);
+}
+
+export class MemoryStore {
+  constructor({ storePath = STORE_PATH } = {}) {
+    this.storePath = storePath;
+    this.memories = [];
+    this._key = null;
+  }
+
+  get size() { return this.memories.length; }
+
+  get bytes() {
+    try { return existsSync(this.storePath) ? statSync(this.storePath).size : 0; } catch { return 0; }
+  }
+
+  key() {
+    if (!this._key) this._key = loadOrCreateKey();
+    return this._key;
+  }
+
+  // Fail-open on a missing or corrupt file — memory is an enhancement, and refusing to start
+  // the gateway because one cache file is unreadable trades a small loss for a total one.
+  // A record that fails validation is DROPPED, never repaired: it would otherwise be handed
+  // to a model as a standing fact about the user.
+  load() {
+    try {
+      if (!existsSync(this.storePath)) return this;
+      const raw = JSON.parse(decrypt(this.key(), JSON.parse(readFileSync(this.storePath, 'utf8'))).toString('utf8'));
+      this.memories = (Array.isArray(raw) ? raw : [])
+        .map((m) => { try { return upcastMemory(m); } catch { return null; } })
+        .filter((m) => m && isValidMemory(m));
+    } catch {
+      this.memories = [];
+    }
+    return this;
+  }
+
+  persistNow() {
+    try {
+      mkdirSync(dirname(this.storePath), { recursive: true });
+      writeFileSync(this.storePath, JSON.stringify(encrypt(this.key(), Buffer.from(JSON.stringify(this.memories), 'utf8'))), { mode: 0o600 });
+    } catch { /* a failed cache write must not fail the call that triggered it */ }
+  }
+
+  #commit(list) {
+    const { kept } = pruneMemories(list, { now: Date.now(), max: DEFAULT_MAX_MEMORIES });
+    this.memories = kept.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+    this.persistNow();
+    return this.memories;
+  }
+
+  list() { return this.memories; }
+
+  /** Save one memory, reconciled against what is held. The only write path. */
+  remember(input) {
+    const now = Date.now();
+    const { action, record, replaces } = reconcile(this.memories, input, { now, newId: uid });
+    this.#commit([record, ...(replaces ? this.memories.filter((m) => m.id !== replaces.id) : this.memories)]);
+    return { action, record, replaces };
+  }
+
+  /** Drop by id, or by however a person named it ("forget the Frankfurt thing"). */
+  forget(query) {
+    const q = String(query || '').trim();
+    const hits = this.memories.some((m) => m.id === q)
+      ? this.memories.filter((m) => m.id === q)
+      : matchForForget(this.memories, q);
+    if (!hits.length) return { removed: [] };
+    const gone = new Set(hits.map((m) => m.id));
+    this.#commit(this.memories.filter((m) => !gone.has(m.id)));
+    return { removed: hits };
+  }
+
+  /** The memories a turn should carry, and the rendered block — the SAME ranking the panel uses. */
+  recall({ text = '', scopes = ['global'], limit, maxChars } = {}) {
+    const chosen = recall(this.memories, {
+      text, scopes, now: Date.now(),
+      ...(limit ? { limit } : {}),
+      ...(maxChars ? { maxChars } : {}),
+    });
+    if (chosen.length) {
+      this.memories = markUsed(this.memories, chosen.map((m) => m.id), { now: Date.now() });
+      this.persistNow();
+    }
+    return { memories: chosen, block: memoryBlock(chosen) };
+  }
+
+  /**
+   * Bulk merge from the extension's sync. Every incoming record goes through `reconcile`, so
+   * a repeated push is a no-op rather than a doubling — that idempotence is what makes the
+   * two-way sync safe.
+   */
+  bulk({ upserts = [], removes = [] } = {}) {
+    for (const id of removes) {
+      const gone = new Set([String(id)]);
+      this.memories = this.memories.filter((m) => !gone.has(m.id));
+    }
+    let merged = 0;
+    for (const raw of upserts) {
+      let candidate;
+      try { candidate = normalizeMemory(raw, { now: Date.now(), newId: uid }); } catch { continue; }
+      const { action, record, replaces } = reconcile(this.memories, candidate, { now: Date.now(), newId: uid });
+      if (action === 'duplicate') continue;
+      this.#commit([record, ...(replaces ? this.memories.filter((m) => m.id !== replaces.id) : this.memories)]);
+      merged += 1;
+    }
+    if (removes.length && !merged) this.#commit(this.memories);
+    return { size: this.memories.length, merged };
+  }
+
+  clear() {
+    const dropped = this.memories.length;
+    this.#commit([]);
+    return dropped;
+  }
+}
+
+export async function createMemoryStore(opts) {
+  return new MemoryStore(opts).load();
+}

package/src/memory.js

@@ -0,0 +1,642 @@
+// VENDORED from @chatpanel/events/memory.js — edit there, then copy over.
+// Same pattern as observability.js and rrf.js: one pure module copied in rather than pulling
+// the whole events package. Source of truth: chatpanel-events/memory.js.
+//
+/**
+ * MEMORY — the small set of durable facts about the user that every model should already know.
+ *
+ * ChatPanel remembers conversations, meetings and notes, and can search all of them. What it
+ * could not do is KNOW anything. Told "call me Alex, and never open with a preamble", the next
+ * turn — let alone the next agent, or Codex over MCP — started from zero, because the only way
+ * a fact survived was for someone to search for it, and nobody searches for their own name.
+ *
+ * Memory is the opposite of history by design. History is large, retrieved, and about events.
+ * Memory is SMALL, ambient, and about standing truths — so it can be carried into every turn
+ * instead of looked up, and so a person can read the whole of it in one screen and correct it.
+ * That size limit is the feature: a memory that grows without bound becomes a second corpus,
+ * and a second corpus needs search, and then nothing is ambient any more.
+ *
+ * Four properties make it work the same everywhere:
+ *
+ *   ONE VOCABULARY. Five kinds, closed set. `identity` and `preference` are AMBIENT — they
+ *   apply to every turn, so they are carried unconditionally. `project`, `fact` and
+ *   `reference` are RETRIEVED, because "the staging cluster is in Frankfurt" is only worth
+ *   tokens on a turn that mentions it. One rule decides which, in `recall`, so the extension,
+ *   the gateway and a future mobile client cannot disagree about what the model was told.
+ *
+ *   CAPTURE IS DETERMINISTIC. `candidatesFrom` reads a string. No model call, no network, no
+ *   latency, on every user message — which is the only reason it can run on every user
+ *   message. It separates what the user COMMANDED ("remember that…") from what they merely
+ *   REVEALED ("I prefer…"), because those deserve different answers: the first is consent,
+ *   the second is a guess, and a guess must be offered rather than acted on.
+ *
+ *   WRITES RECONCILE, THEY DO NOT ACCUMULATE. Saying "call me Alex" twice must leave one
+ *   memory, and saying "actually, call me Sam" must leave one memory with the new value and
+ *   the old one recoverable. `reconcile` decides create/update/duplicate against what is
+ *   already stored; a client that just pushes rows produces a list nobody can read by week
+ *   two.
+ *
+ *   THE PROMPT FORM IS SHARED. `memoryBlock` is the one rendering. If the extension wrote its
+ *   own the model would be told something subtly different depending on which surface the
+ *   user typed into, and the bug would be invisible.
+ *
+ * Class R: pure, dependency-free, no I/O. Persistence is the host's (chrome.storage in the
+ * extension, an encrypted file in the gateway) — the same split as `store.js`.
+ */
+
+export const MEMORY_VERSION = 1;
+
+/**
+ * The closed vocabulary. Deliberately five: enough that a memory's kind tells you how to
+ * treat it, few enough that a person choosing one does not have to think.
+ *
+ * `ambient` is the load-bearing bit — it is not a label, it is the retrieval rule.
+ */
+export const MEMORY_KINDS = Object.freeze({
+  identity: { label: 'Identity', ambient: true, hint: 'Who the user is — name, role, pronouns, language, timezone.' },
+  preference: { label: 'Preference', ambient: true, hint: 'How they want things done — tone, format, defaults, things never to do.' },
+  project: { label: 'Project', ambient: false, hint: 'Ongoing work, goals and constraints not derivable from the material itself.' },
+  fact: { label: 'Fact', ambient: false, hint: 'A durable fact about their world — systems, teams, environments, conventions.' },
+  reference: { label: 'Reference', ambient: false, hint: 'A pointer to something external — a URL, a dashboard, a ticket, a doc.' },
+});
+
+export const MEMORY_KIND_NAMES = Object.freeze(Object.keys(MEMORY_KINDS));
+
+/** Kinds carried on every turn regardless of what was said. */
+export const AMBIENT_KINDS = Object.freeze(MEMORY_KIND_NAMES.filter((k) => MEMORY_KINDS[k].ambient));
+
+/**
+ * Bounds. A memory longer than this is a note, and there is already a notes feature; a store
+ * larger than this is a corpus, and there is already a history feature. Both limits exist to
+ * stop memory turning into the thing next to it.
+ */
+export const MAX_MEMORY_CHARS = 280;
+export const MIN_MEMORY_CHARS = 3;
+export const DEFAULT_MAX_MEMORIES = 200;
+/** Prompt budget for the injected block. ~100 tokens; enough for a readable standing brief. */
+export const DEFAULT_BLOCK_CHARS = 1200;
+
+export class MemoryError extends Error {
+  constructor(message) { super(message); this.name = 'MemoryError'; }
+}
+
+// --------------------------------------------------------------------------
+// The record
+// --------------------------------------------------------------------------
+
+/**
+ * Normalize anything memory-shaped into the canonical record. Throws MemoryError on input
+ * that cannot be a memory — callers get one validation path rather than each inventing
+ * their own defaults.
+ *
+ * `now` and `newId` are injected for the same reason they are in `event.js`: a pure module
+ * that reads the clock cannot be replayed or tested.
+ *
+ * @returns {{
+ *   id: string, v: number, text: string, kind: string, scope: string, key: string,
+ *   tags: string[], pinned: boolean, source: object, confidence: number,
+ *   createdAt: number, updatedAt: number, usedAt: number, useCount: number,
+ *   expiresAt: number|null, history: {text: string, at: number}[]
+ * }}
+ */
+export function normalizeMemory(input = {}, { now = 0, newId = null } = {}) {
+  const text = collapse(input.text);
+  if (text.length < MIN_MEMORY_CHARS) throw new MemoryError('a memory needs text');
+  if (text.length > MAX_MEMORY_CHARS) {
+    throw new MemoryError(`a memory must be at most ${MAX_MEMORY_CHARS} characters — save longer material as a note`);
+  }
+  const kind = MEMORY_KINDS[input.kind] ? input.kind : 'fact';
+  const at = Number(input.createdAt) || Number(now) || 0;
+  return {
+    id: String(input.id || (newId ? newId() : '') || ''),
+    v: MEMORY_VERSION,
+    text,
+    kind,
+    // Free-form so a client can scope to an agent, a workspace or a site without this module
+    // enumerating surfaces it cannot know about. 'global' means every turn everywhere.
+    scope: String(input.scope || 'global'),
+    key: memoryKey(text),
+    // Derived, not asked for — see slotOf. An explicit slot still wins.
+    slot: collapse(input.slot).toLowerCase() || slotOf(text),
+    tags: [...new Set((input.tags || []).map((t) => collapse(t).toLowerCase()).filter(Boolean))].slice(0, 8),
+    pinned: !!input.pinned,
+    // WHERE IT CAME FROM, always. A memory the user cannot trace is a memory they cannot
+    // trust, and the first thing anyone asks of a wrong one is "when did I say that".
+    source: {
+      via: String(input.source?.via || 'user'),      // user | agent | import | mcp
+      surface: String(input.source?.surface || ''),  // chat | notes | meeting | mcp | settings
+      ref: String(input.source?.ref || ''),          // conversation/meeting/note id
+      agent: String(input.source?.agent || ''),      // which model or CLI proposed it
+    },
+    // How sure the CAPTURE was, not how true the fact is. An explicit command is 1.
+    confidence: clamp01(input.confidence == null ? 1 : Number(input.confidence)),
+    createdAt: at,
+    updatedAt: Number(input.updatedAt) || at,
+    usedAt: Number(input.usedAt) || 0,
+    useCount: Math.max(0, Math.floor(Number(input.useCount) || 0)),
+    expiresAt: input.expiresAt ? Number(input.expiresAt) : null,
+    // Bounded supersession ledger — "you used to say X" without an unbounded audit log.
+    history: (input.history || []).slice(-5).map((h) => ({ text: collapse(h.text), at: Number(h.at) || 0 })),
+  };
+}
+
+/** True when `rec` is a well-formed memory. Never throws — for filtering a loaded store. */
+export function isValidMemory(rec) {
+  try { normalizeMemory(rec, { now: rec?.createdAt || 1 }); return !!rec?.id; } catch { return false; }
+}
+
+/**
+ * The identity of a FACT rather than of a record — two phrasings of the same standing truth
+ * should collide here so `reconcile` can supersede rather than accumulate.
+ *
+ * Lowercased, stripped of punctuation and of the framing words people vary freely ("I always
+ * prefer" / "prefer"), then the remaining words sorted and deduped. Sorting is safe precisely
+ * because this is a dedup key and never a display value: "deploy on fridays" and "on fridays,
+ * deploy" are the same standing fact, and treating them as two is the failure this prevents.
+ */
+export function memoryKey(text) {
+  const words = collapse(text)
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]/gu, ' ')
+    .split(/\s+/)
+    .filter((w) => w && !KEY_STOPWORDS.has(w));
+  return [...new Set(words)].sort().join(' ');
+}
+
+const KEY_STOPWORDS = new Set([
+  'a', 'an', 'the', 'i', 'im', 'me', 'my', 'mine', 'we', 'our', 'us', 'you', 'your',
+  'is', 'am', 'are', 'was', 'were', 'be', 'been', 'being', 'do', 'does', 'did',
+  'to', 'of', 'in', 'on', 'at', 'for', 'with', 'and', 'or', 'that', 'this', 'it',
+  'please', 'always', 'usually', 'generally', 'really', 'just', 'very', 'so',
+  'remember', 'note', 'noting', 'user', 'prefer', 'prefers', 'preferred', 'like', 'likes',
+]);
+
+/**
+ * THE SLOT A MEMORY FILLS, when it fills one — derived from the text itself.
+ *
+ * Token overlap cannot see that "Goes by Alex" and "Goes by Sam" are the same fact with a new
+ * value: they share two words out of four, which is exactly what two unrelated memories look
+ * like. So changing your name produced a SECOND memory and the model was told both.
+ *
+ * A slot is the subject a statement is about. Two memories with the same slot are one memory,
+ * whatever their words, so the later one supersedes. Deriving it from the text rather than
+ * asking the caller means it works identically for a captured phrase and for a `memory` tool
+ * call from some agent that has never heard of slots.
+ *
+ * Returns '' when a statement is not slot-shaped ("Deploys on Fridays"), which is most of
+ * them — those fall back to key and similarity matching.
+ */
+export function slotOf(text) {
+  const t = collapse(text).toLowerCase().replace(/^the\s+/, '');
+  // Identity phrasings all name the same slot, or the user's name lives in three places.
+  if (/^(?:goes by|name is|is called|called)\b/.test(t)) return 'name';
+  if (/^pronouns\b/.test(t)) return 'pronouns';
+  // "<subject> is/are <value>" — the general form. Bounded to a short subject so a whole
+  // sentence containing "is" somewhere does not become a slot that swallows its neighbours.
+  const m = /^(?:my\s+|their\s+)?([\p{L}\p{N}][\p{L}\p{N} '-]{0,28}?)\s+(?:is|are|was|were)\b/u.exec(t);
+  if (!m) return '';
+  const subject = m[1].split(/\s+/).filter((w) => !KEY_STOPWORDS.has(w)).join(' ');
+  return subject.length >= 3 ? subject : '';
+}
+
+/** Token-set overlap, 0..1 — "prefers terse answers" vs "prefers terse replies". */
+export function similarity(a, b) {
+  const A = new Set(memoryKey(a).split(' ').filter(Boolean));
+  const B = new Set(memoryKey(b).split(' ').filter(Boolean));
+  if (!A.size || !B.size) return 0;
+  let hit = 0;
+  for (const w of A) if (B.has(w)) hit += 1;
+  return hit / (A.size + B.size - hit);
+}
+
+/**
+ * How much of the SHORTER phrase the longer one contains, 0..1. Different question from
+ * `similarity`, and the right one for "forget the Frankfurt thing": a person names a memory by
+ * one distinctive word, not by restating it, so a symmetric measure scores that near zero.
+ */
+export function containment(a, b) {
+  const A = new Set(memoryKey(a).split(' ').filter(Boolean));
+  const B = new Set(memoryKey(b).split(' ').filter(Boolean));
+  if (!A.size || !B.size) return 0;
+  let hit = 0;
+  for (const w of A) if (B.has(w)) hit += 1;
+  return hit / Math.min(A.size, B.size);
+}
+
+/** Above this, two memories are the same standing fact stated differently. */
+export const SAME_FACT = 0.8;
+
+// --------------------------------------------------------------------------
+// Capture — reading a message for things worth keeping
+// --------------------------------------------------------------------------
+
+/**
+ * COMMANDS. The user is addressing the assistant and telling it to keep something. The capture
+ * group is the fact itself, so "remember that I deploy on Fridays" stores "I deploy on
+ * Fridays" and not the instruction wrapping it.
+ *
+ * Each carries the kind it implies, because "call me Alex" is an identity and "from now on,
+ * be terse" is a preference, and making the user pick afterwards is a step they should not
+ * have to take.
+ */
+const COMMANDS = [
+  { re: /^(?:please\s+)?(?:remember|memorize|memorise)(?:\s+that|\s+this)?[:,]?\s+(.+)$/i, kind: 'fact' },
+  { re: /^(?:please\s+)?(?:keep in mind|bear in mind|don'?t forget|do not forget)(?:\s+that)?[:,]?\s+(.+)$/i, kind: 'fact' },
+  { re: /^(?:please\s+)?(?:make a note|note)(?:\s+that|\s+of)[:,]?\s+(.+)$/i, kind: 'fact' },
+  { re: /^(?:from now on|going forward|in future|in the future|henceforth)[:,]?\s+(.+)$/i, kind: 'preference' },
+  { re: /^(?:call me|i go by|refer to me as)\s+(.+)$/i, kind: 'identity', rebuild: (m) => `Goes by ${trimEnd(m[1])}` },
+  { re: /^my name(?:'s| is)\s+(.+)$/i, kind: 'identity', rebuild: (m) => `Name is ${trimEnd(m[1])}` },
+  { re: /^(?:always|never)\s+(.+)$/i, kind: 'preference', rebuild: (m, raw) => sentence(raw) },
+];
+
+/**
+ * REVEALS. Not addressed to the assistant at all — the user simply said something durable
+ * about themselves in passing. These are OFFERED, never saved, because the inference is
+ * exactly the kind that is right often enough to be useful and wrong often enough to be
+ * insulting if acted on silently.
+ */
+const REVEALS = [
+  { re: /^i (?:prefer|like|want|need)\s+(.+)$/i, kind: 'preference', confidence: 0.7 },
+  { re: /^i (?:hate|dislike|don'?t like|do not like|can'?t stand)\s+(.+)$/i, kind: 'preference', confidence: 0.7 },
+  { re: /^i(?:'m| am)(?: a| an| the)?\s+(.+)$/i, kind: 'identity', confidence: 0.6 },
+  { re: /^i (?:work|working) (?:on|at|with)\s+(.+)$/i, kind: 'project', confidence: 0.6 },
+  { re: /^i(?:'m| am) (?:working|building|writing) (?:on\s+)?(.+)$/i, kind: 'project', confidence: 0.6 },
+  { re: /^(?:we|our team|my team) (?:use|uses|are using|run|runs|deploy|deploys)\s+(.+)$/i, kind: 'fact', confidence: 0.6 },
+  { re: /^my (?:\w+\s){0,2}?(?:is|are)\s+(.+)$/i, kind: 'fact', confidence: 0.55 },
+];
+
+/** Removal is a command too, and it must be recognised or "forget that" gets stored as a fact. */
+const FORGETS = [
+  /^(?:please\s+)?forget(?:\s+that|\s+about)?[:,]?\s+(.+)$/i,
+  /^(?:please\s+)?(?:stop remembering|no longer remember|un-?remember)[:,]?\s+(.+)$/i,
+];
+
+/**
+ * A trigger word inside a QUESTION is not an instruction — "do you remember what we decided?"
+ * asks for recall, and storing it as a fact is the single most obvious way to make this
+ * feature look broken. Likewise "I can't remember" is a complaint, not a command.
+ */
+const NOT_A_COMMAND = /(?:^|\s)(?:do|does|did|can|could|would|will|what|when|where|who|why|how|are|is)\s+(?:you|i|we|it)\b/i;
+const NEGATED = /\b(?:can'?t|cannot|don'?t|do not|couldn'?t|never|didn'?t)\s+(?:seem to\s+)?(?:remember|recall|forget)\b/i;
+
+/**
+ * Read one user message for things worth keeping.
+ *
+ * Returns candidates in the order found. `explicit: true` means the user issued a command and
+ * the host may save it without asking; `explicit: false` means offer it and let them tap.
+ * That distinction is the whole capture policy, and it lives here rather than in a client so
+ * the panel, the gateway and a mobile app cannot each pick a different one.
+ *
+ * @param text  one user message.
+ * @param opts.maxCandidates cap per message (default 3) — a wall of chips is not a prompt.
+ * @param opts.includeReveals set false for surfaces with nowhere to show an offer.
+ * @returns {{op: 'remember'|'forget', text: string, kind: string, confidence: number,
+ *            explicit: boolean, trigger: string}[]}
+ */
+export function candidatesFrom(text, { maxCandidates = 3, includeReveals = true } = {}) {
+  const out = [];
+  const raw = String(text || '');
+  // Fenced code is material, not speech. A README line that happens to start "I prefer" is
+  // not the user telling us anything.
+  const speech = raw.replace(/```[\s\S]*?```/g, ' ').replace(/`[^`]*`/g, ' ');
+
+  for (const line of splitStatements(speech)) {
+    if (out.length >= maxCandidates) break;
+    if (line.length < MIN_MEMORY_CHARS) continue;
+    if (NEGATED.test(line)) continue;
+
+    let matched = false;
+    for (const re of FORGETS) {
+      const m = re.exec(line);
+      if (!m) continue;
+      const body = clip(trimEnd(m[1]));
+      if (body.length >= MIN_MEMORY_CHARS) {
+        out.push({ op: 'forget', text: body, kind: 'fact', confidence: 1, explicit: true, trigger: 'forget' });
+        matched = true;
+      }
+      break;
+    }
+    if (matched) continue;
+
+    // A question mark alone is not disqualifying — "remember that the demo is Friday?" is a
+    // command with a tag. It is the interrogative SHAPE that rules a command out.
+    if (NOT_A_COMMAND.test(line)) continue;
+
+    for (const { re, kind, rebuild } of COMMANDS) {
+      const m = re.exec(line);
+      if (!m) continue;
+      const body = clip(rebuild ? rebuild(m, line) : sentence(trimEnd(m[1])));
+      if (body.length >= MIN_MEMORY_CHARS) {
+        out.push({ op: 'remember', text: body, kind, confidence: 1, explicit: true, trigger: 'command' });
+        matched = true;
+      }
+      break;
+    }
+    if (matched || !includeReveals) continue;
+
+    for (const { re, kind, confidence } of REVEALS) {
+      if (!re.test(line)) continue;
+      const body = clip(sentence(line));
+      // Two words minimum: "I am tired" is durable-looking and worthless. The floor is crude
+      // on purpose — the cost of a bad offer is one ignored chip, and the cost of a clever
+      // filter is a fact the user watched get dropped.
+      if (body.split(/\s+/).length >= 3) {
+        out.push({ op: 'remember', text: body, kind, confidence, explicit: false, trigger: 'reveal' });
+      }
+      break;
+    }
+  }
+  return out.slice(0, maxCandidates);
+}
+
+// --------------------------------------------------------------------------
+// Reconcile — what a write does to what is already there
+// --------------------------------------------------------------------------
+
+/**
+ * Decide what saving `incoming` means against the memories already held.
+ *
+ *   duplicate — the same fact, said the same way. Nothing to do but touch it.
+ *   update    — the same fact, restated or changed. Supersede in place, keep the old text.
+ *   create    — genuinely new.
+ *
+ * There is deliberately no `conflict`. Two contradictory statements cannot be told apart from
+ * a correction without understanding the sentence, and a memory system that asks "did you
+ * mean to change your mind?" is a memory system people turn off. The later statement wins and
+ * the earlier one stays visible in `history`.
+ *
+ * @returns {{action: 'create'|'update'|'duplicate', record: object, replaces: object|null}}
+ */
+export function reconcile(memories, incoming, { now = 0, newId = null } = {}) {
+  const next = normalizeMemory(incoming, { now, newId });
+  const pool = (memories || []).filter((m) => m && m.scope === next.scope);
+
+  // Slot first: it is the only one of the three that can recognise a CHANGED VALUE, which is
+  // what a correction is. Then exact key, then near-identical wording.
+  const match = (next.slot && pool.find((m) => m.slot === next.slot))
+    || pool.find((m) => m.key === next.key)
+    || pool.find((m) => m.kind === next.kind && similarity(m.text, next.text) >= SAME_FACT);
+
+  if (!match) return { action: 'create', record: next, replaces: null };
+
+  if (collapse(match.text).toLowerCase() === next.text.toLowerCase()) {
+    // Restating a memory is a signal about it: it is still true, and it is on the user's mind.
+    return {
+      action: 'duplicate',
+      record: { ...match, updatedAt: Number(now) || match.updatedAt, useCount: match.useCount + 1 },
+      replaces: match,
+    };
+  }
+
+  return {
+    action: 'update',
+    record: {
+      ...match,
+      text: next.text,
+      key: next.key,
+      slot: next.slot,
+      kind: next.kind,
+      tags: next.tags.length ? next.tags : match.tags,
+      confidence: next.confidence,
+      source: next.source,
+      updatedAt: Number(now) || match.updatedAt,
+      history: [...match.history, { text: match.text, at: match.updatedAt }].slice(-5),
+    },
+    replaces: match,
+  };
+}
+
+/**
+ * Which stored memories a "forget X" refers to. Matches by id, then by exact key, then by
+ * similarity — a person says "forget the Frankfurt thing", not a uuid.
+ */
+export function matchForForget(memories, query, { limit = 5 } = {}) {
+  const q = collapse(query);
+  if (!q) return [];
+  const byId = (memories || []).filter((m) => m.id === q);
+  if (byId.length) return byId;
+  const key = memoryKey(q);
+  return (memories || [])
+    .map((m) => ({ m, s: m.key === key ? 1 : Math.max(similarity(m.text, q), containment(q, m.text)) }))
+    .filter((x) => x.s >= 0.5)
+    .sort((a, b) => b.s - a.s)
+    .slice(0, limit)
+    .map((x) => x.m);
+}
+
+// --------------------------------------------------------------------------
+// Recall — what the model is told, this turn
+// --------------------------------------------------------------------------
+
+/**
+ * Choose the memories for one turn, within a character budget.
+ *
+ * Ambient kinds (identity, preference) come first and unconditionally: they are how the user
+ * wants to be spoken to, and a turn that fails to mention their name is still a turn where
+ * their name applies. Everything else is scored against the turn's text — a project memory
+ * earns its tokens only when the turn is about it.
+ *
+ * Pinned always wins, of any kind. That is the user's explicit override of this whole ranking.
+ *
+ * @param memories all stored memories.
+ * @param opts.text the turn's text (user message, or the question for a tool call).
+ * @param opts.scopes which scopes apply — 'global' plus, say, `agent:claude-code`.
+ * @param opts.maxChars budget for the rendered block.
+ * @returns the chosen memories, most important first.
+ */
+export function recall(memories, {
+  text = '', scopes = ['global'], kinds = null, now = 0,
+  limit = 24, maxChars = DEFAULT_BLOCK_CHARS, includeAmbient = true,
+} = {}) {
+  const scopeSet = new Set(scopes.length ? scopes : ['global']);
+  const terms = new Set(memoryKey(text).split(' ').filter(Boolean));
+
+  const live = (memories || [])
+    .filter((m) => m && m.text)
+    .filter((m) => scopeSet.has(m.scope))
+    .filter((m) => !kinds || kinds.includes(m.kind))
+    .filter((m) => !m.expiresAt || !now || m.expiresAt > now);
+
+  const scored = live.map((m) => {
+    const words = new Set(m.key.split(' ').filter(Boolean));
+    let overlap = 0;
+    for (const w of words) if (terms.has(w)) overlap += 1;
+    const relevance = words.size ? overlap / words.size : 0;
+    const ambient = includeAmbient && MEMORY_KINDS[m.kind]?.ambient;
+    // Recency and use are TIE-BREAKS, not drivers. A fact does not become truer because it
+    // was mentioned recently, but between two equally relevant ones the live one is the
+    // better guess.
+    const freshness = now && m.updatedAt ? Math.max(0, 1 - (now - m.updatedAt) / YEAR) : 0;
+    const used = Math.min(1, m.useCount / 10);
+    return {
+      m,
+      keep: m.pinned || ambient || relevance > 0,
+      score: (m.pinned ? 100 : 0) + (ambient ? 10 : 0) + relevance * 8 + freshness + used,
+    };
+  });
+
+  const out = [];
+  let chars = 0;
+  for (const { m, keep, score } of scored.filter((s) => s.keep).sort((a, b) => b.score - a.score)) {
+    if (out.length >= limit) break;
+    const cost = m.text.length + m.kind.length + 6;
+    if (chars + cost > maxChars && out.length) break;
+    chars += cost;
+    out.push(m);
+    void score;
+  }
+  return out;
+}
+
+const YEAR = 365 * 24 * 60 * 60 * 1000;
+
+/**
+ * The ONE prompt rendering. Every surface that puts memory in front of a model uses this, so
+ * "what the model was told" is a single, reviewable string rather than per-client prose.
+ *
+ * Returns '' for an empty set — callers can concatenate unconditionally.
+ */
+export function memoryBlock(memories, { heading = 'What you already know about this user', maxChars = DEFAULT_BLOCK_CHARS } = {}) {
+  const list = (memories || []).filter((m) => m && m.text);
+  if (!list.length) return '';
+  const lines = [];
+  let chars = 0;
+  for (const m of list) {
+    const line = `- (${m.kind}) ${m.text}`;
+    if (chars + line.length > maxChars && lines.length) break;
+    chars += line.length + 1;
+    lines.push(line);
+  }
+  return [
+    `## ${heading}`,
+    'Saved by the user in ChatPanel and true across conversations, agents and devices.',
+    'Apply them without being asked and without announcing them.',
+    ...lines,
+    'If the user states something durable about themselves, their preferences or their work,'
+    + ' save it with the `memory` tool. If they correct one of these, update it — do not just agree.',
+  ].join('\n');
+}
+
+/** Mark memories as used this turn. Recall quality depends on it, so it is not optional. */
+export function markUsed(memories, ids, { now = 0 } = {}) {
+  const set = new Set(ids || []);
+  return (memories || []).map((m) => (set.has(m.id)
+    ? { ...m, usedAt: Number(now) || m.usedAt, useCount: m.useCount + 1 }
+    : m));
+}
+
+/**
+ * Drop what has expired, then hold the store to `max` by evicting the least valuable.
+ *
+ * Eviction order is the inverse of value: never pinned, never ambient, then least used and
+ * least recently touched. Returns both halves so a client can TELL the user what went rather
+ * than silently shrinking their memory.
+ */
+export function pruneMemories(memories, { now = 0, max = DEFAULT_MAX_MEMORIES } = {}) {
+  const all = (memories || []).filter(Boolean);
+  const expired = now ? all.filter((m) => m.expiresAt && m.expiresAt <= now) : [];
+  let kept = expired.length ? all.filter((m) => !expired.includes(m)) : all;
+  const dropped = [...expired];
+
+  if (kept.length > max) {
+    const value = (m) => (m.pinned ? 3 : 0) + (MEMORY_KINDS[m.kind]?.ambient ? 1 : 0);
+    const ranked = [...kept].sort((a, b) => value(b) - value(a)
+      || b.useCount - a.useCount
+      || (b.usedAt || b.updatedAt) - (a.usedAt || a.updatedAt));
+    dropped.push(...ranked.slice(max));
+    kept = ranked.slice(0, max);
+  }
+  return { kept, dropped };
+}
+
+// --------------------------------------------------------------------------
+// The tool contract — one definition, every client
+// --------------------------------------------------------------------------
+
+/**
+ * The `memory` tool as the model sees it, shared by the extension's turn toolset and the
+ * gateway's MCP server. A second copy would drift, and the drift would be a model that
+ * behaves differently in Claude Code than in the side panel for no reason a user could see.
+ *
+ * One tool with an `action`, not four tools: memory is a small feature and four schemas
+ * resident on every turn would cost more than the memories themselves.
+ */
+export const MEMORY_TOOL_SPEC = Object.freeze({
+  name: 'memory',
+  description:
+    "Save, update or remove a durable fact about the USER in ChatPanel — carried into every "
+    + 'future conversation, on every model and agent. Use it the moment they state a standing '
+    + 'preference ("always be terse"), an identity fact ("call me Alex"), or a constraint about '
+    + 'their work that will still be true next week. Do NOT use it for one-off task details, '
+    + 'anything already obvious from the conversation, or content that belongs in a note. '
+    + 'Keep each memory one short self-contained sentence. Use `forget` when the user says '
+    + 'something is no longer true, and `list` to see what is already stored before adding.',
+  parameters: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['remember', 'forget', 'list'], description: 'What to do.' },
+      text: { type: 'string', description: `The fact, as one short sentence written in the third person ("Prefers terse answers"). Max ${MAX_MEMORY_CHARS} characters. Required for remember; for forget, the memory to drop (its text or id).` },
+      kind: { type: 'string', enum: MEMORY_KIND_NAMES, description: MEMORY_KIND_NAMES.map((k) => `${k}: ${MEMORY_KINDS[k].hint}`).join(' ') },
+      tags: { type: 'array', items: { type: 'string' }, description: 'Optional short tags for grouping.' },
+    },
+    required: ['action'],
+  },
+});
+
+/** The system text that goes with the tool — why it exists, when NOT to reach for it. */
+export function memoryToolSystem() {
+  return [
+    'You can give the user a memory that survives this conversation, this model and this device'
+    + ' — call the `memory` tool.',
+    'Save when they say something durable about themselves, how they want to be helped, or their'
+    + ' ongoing work. Do not save task details, transient state, or anything they would not want'
+    + ' repeated back to them in a month.',
+    'Saving is a change to the user\'s own data: say in one short clause what you saved.',
+  ].join(' ');
+}
+
+// --------------------------------------------------------------------------
+// Versioning
+// --------------------------------------------------------------------------
+
+/**
+ * Upcasters, empty at v1 — present so the first schema change is a one-line addition rather
+ * than a migration nobody planned for. Same machinery as `upcast.js`.
+ */
+export const MEMORY_UPCASTERS = Object.freeze({});
+
+export function upcastMemory(rec) {
+  let out = rec;
+  for (let v = Number(out?.v) || 1; v < MEMORY_VERSION; v += 1) {
+    const up = MEMORY_UPCASTERS[v];
+    if (!up) throw new MemoryError(`no upcaster from memory v${v}`);
+    out = up(out);
+  }
+  return out;
+}
+
+// --------------------------------------------------------------------------
+// Text helpers
+// --------------------------------------------------------------------------
+
+const collapse = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
+const clamp01 = (n) => (Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 1);
+const trimEnd = (s) => collapse(s).replace(/[.,;:!]+$/, '');
+const clip = (s) => (s.length > MAX_MEMORY_CHARS ? `${s.slice(0, MAX_MEMORY_CHARS - 1).trimEnd()}…` : s);
+const sentence = (s) => {
+  const t = trimEnd(s);
+  return t ? t[0].toUpperCase() + t.slice(1) : t;
+};
+
+/**
+ * Split a message into the statements a trigger could apply to. Newlines and list bullets are
+ * hard boundaries; sentence-ending punctuation is a soft one. Deliberately does NOT split on
+ * commas — "remember that we ship on Friday, not Thursday" is one fact.
+ */
+function splitStatements(text) {
+  return String(text || '')
+    .split(/\n+/)
+    .flatMap((line) => collapse(line).replace(/^[-*+•]\s*|^\d+[.)]\s*/, '').split(/(?<=[.!?])\s+(?=[A-Z"'])/))
+    .map(collapse)
+    .filter(Boolean);
+}

package/src/rrf.js

@@ -0,0 +1,93 @@
+// VENDORED from @chatpanel/events/rrf.js — edit there, then copy over.
+// Same pattern as observability.js: one pure module copied in rather than pulling the whole
+// events package. Source of truth: chatpanel-events/rrf.js.
+//
+// rrf.js — Reciprocal Rank Fusion, and the query planning that feeds it.
+//
+// One question rarely makes one good keyword query. "What was the outcome of the Ben tooling
+// demo?" and "Ben demo decisions action items" retrieve different things, and the answer is
+// usually in the union. RRF merges several ranked lists without needing their scores to be
+// comparable — each list contributes 1/(k+rank) — which is exactly the situation here: BM25
+// scores, vector distances and a hot/warm split are all on different scales.
+//
+// Pure and dependency-free, so the identical fusion runs in the extension (hot+warm), the
+// gateway (multi-query search) and any future client. The extension had this privately; it
+// lives here now so the gateway doesn't grow a second, subtly different copy.
+
+/**
+ * Fuse ranked id lists. `lists` is an array of arrays of ids, each already in rank order.
+ * k dampens the head of each list (60 is the standard default). limit 0 = everything.
+ */
+export function fuseRRF(lists, { k = 60, limit = 0 } = {}) {
+  const score = new Map();
+  for (const list of lists || []) {
+    if (!Array.isArray(list)) continue;
+    list.forEach((id, rank) => {
+      if (id == null) return;
+      score.set(id, (score.get(id) || 0) + 1 / (k + rank));
+    });
+  }
+  const out = [...score.entries()].map(([id, s]) => ({ id, score: s })).sort((a, b) => b.score - a.score);
+  return limit > 0 ? out.slice(0, limit) : out;
+}
+
+// Words that carry no retrieval signal but do dilute BM25 — dropped to build a keyword-only
+// variant of a natural-language question.
+const STOP = new Set(('a an and are as at be been but by can could did do does for from had has have how i if in into is it its me my of on or our ought shall should '
+  + 'so than that the their them then there these they this those to um was we were what when where which who whom why will with would you your about tell show give find get '
+  + 'please could-you was-there did-we').split(/\s+/));
+
+/**
+ * Turn one natural-language question into a small set of complementary queries — the cheap,
+ * deterministic half of query expansion. No model call, so it costs nothing and cannot fail.
+ *
+ * A CALLING AGENT can do better (it understands the domain), which is why the tools accept an
+ * explicit `queries` list; these variants are the floor, not the ceiling.
+ */
+export function planQueries(question, { extra = [], max = 4 } = {}) {
+  const q = String(question || '').trim();
+  const out = [];
+  const seen = new Set();
+  const add = (s) => {
+    const t = String(s || '').trim().replace(/\s+/g, ' ');
+    const key = t.toLowerCase();
+    if (t && !seen.has(key)) { seen.add(key); out.push(t); }
+  };
+
+  add(q);                                    // the question as asked
+  for (const e of extra) add(e);             // whatever the agent proposed — it knows more
+
+  const words = q.toLowerCase().match(/[a-z0-9][a-z0-9'’_+-]*/g) || [];
+  const keywords = words.filter((w) => !STOP.has(w) && w.length > 2);
+  if (keywords.length >= 2) add(keywords.join(' '));          // keyword-only: BM25's best shape
+  // The rarest-looking terms (longest words are a decent proxy for specificity) — helps when
+  // the full question is too broad to rank anything well.
+  if (keywords.length > 3) add([...keywords].sort((a, b) => b.length - a.length).slice(0, 3).join(' '));
+
+  return out.slice(0, Math.max(1, max));
+}
+
+/**
+ * Run several queries through one `search(query, opts)` function and fuse the results by id.
+ * `search` returns arrays of { id, ... }; the fused output keeps the richest record seen for
+ * each id (so snippets survive) and reports which queries found it — the "why is this here"
+ * a reader needs when a multi-query search surfaces something unexpected.
+ */
+export async function multiSearch(queries, search, { limit = 10, k = 60 } = {}) {
+  const lists = [];
+  const byId = new Map();
+  const foundBy = new Map();
+  for (const q of queries || []) {
+    let rows = [];
+    try { rows = (await search(q)) || []; } catch { rows = []; } // one bad query must not sink the rest
+    lists.push(rows.map((r) => r.id));
+    for (const r of rows) {
+      if (!byId.has(r.id) || (!byId.get(r.id).snippet && r.snippet)) byId.set(r.id, r);
+      if (!foundBy.has(r.id)) foundBy.set(r.id, []);
+      foundBy.get(r.id).push(q);
+    }
+  }
+  return fuseRRF(lists, { k, limit }).map(({ id, score }) => ({
+    ...byId.get(id), id, score, foundBy: foundBy.get(id) || [],
+  }));
+}

package/src/server.js

@@ -31,6 +31,7 @@ import { shaperFor } from './shape.js';
 import { startNer } from './ner.js';
 import { installTimestampedConsole } from './log.js';
 import { saveBackupSecret, clearBackupSecret, loadBackupSecret, hasBackupSecret } from './history-store.js';
+import { createMemoryStore } from './memory-store.js';
 import { createHistoryStore } from './sqlite-store.js';
 import { ingestBackups } from './backup-ingest.js';
 import * as nerEngine from './ner-engine.js';
@@ -43,17 +44,19 @@ import { publicConfig, applyConfigPatch, applyNerModelSelection, persistConfig,
 import { resolveDestination, aggregateModelsAsync } from './router.js';
 import { makeAccessEvent } from './observability.js';
 import { createPersistentAccessLog } from './access-log-store.js';
+import { planQueries, multiSearch } from './rrf.js';
 import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.43';
+export const VERSION = '0.6.45';
 
 // WARM search tier — SQLite + FTS5 record store (falls back to an encrypted-JSON
 // store if SQLite can't load), fed by the extension's ingest sync + backup-ingest.
 // Persistent + memory-mapped, so a restart needs no re-ingest (no cold start).
 // See docs/architecture-data-tiers.
 const historyStore = await createHistoryStore();
+const memoryStore = await createMemoryStore();
 
 // OBSERVABILITY — a ring of "which agent read what, when", persisted across restarts (the
 // gateway updates often; an empty panel after each restart reads as "nothing is set up").
@@ -62,7 +65,7 @@ const historyStore = await createHistoryStore();
 // metadata only — client/tool/ms + a REDACTED note (a search query's text is never in it).
 const accessLog = createPersistentAccessLog();
 
-const KNOWN_AGENTS = new Set(['codex', 'claude', 'opencode', 'pi', 'kiro', 'antigravity']);
+const KNOWN_AGENTS = new Set(['codex', 'claude', 'opencode', 'pi', 'kiro', 'antigravity', 'hermes']);
 
 // Auto-narrow: arm only the top-K most-relevant MCP tools per turn (speed). Mirrors
 // the extension's AUTO mode via the SAME shared ranker. We narrow only tools whose
@@ -538,6 +541,15 @@ export function createGateway(cfg = loadConfig()) {
     if ((pathname === '/v1/history/ingest' || pathname === '/v1/history/clear') && req.method === 'POST' && !isAdminAuthorized(req)) {
       return sendJson(res, 403, { error: { message: 'history write — extension origin or gateway token required', type: 'forbidden' } });
     }
+    // Memory WRITES follow the same rule as history ingest, for a stronger reason: a memory is
+    // carried into every future turn on every model, so a drive-by localhost page that could
+    // POST one would be installing a standing instruction, not injecting a single record.
+    // Reads stay open — that IS the product (Codex and Claude Code recall through it).
+    if ((pathname === '/v1/memory/remember' || pathname === '/v1/memory/forget'
+      || pathname === '/v1/memory/sync' || pathname === '/v1/memory/clear')
+      && req.method === 'POST' && !isAdminAuthorized(req)) {
+      return sendJson(res, 403, { error: { message: 'memory write — extension origin or gateway token required', type: 'forbidden' } });
+    }
     // The access log is who-read-what — sensitive, and writable only by the local MCP
     // process (which sends the gateway token). Extension Origin or token for both the
     // read (dashboard) and the report (MCP child); a drive-by page has neither.
@@ -597,6 +609,80 @@ export function createGateway(cfg = loadConfig()) {
         return sendJson(res, 400, { error: { message: `ingest failed: ${e.message}`, type: 'ingest_error' } });
       }
     }
+    // --- MEMORY. Small, durable facts about the user, reachable by every local agent.
+    //   GET  /v1/memory/list                      → { memories }
+    //   POST /v1/memory/recall  { text, scopes }  → { memories, block }
+    //   POST /v1/memory/remember { text, kind, … }→ { action, record }
+    //   POST /v1/memory/forget  { query }         → { removed }
+    //   POST /v1/memory/sync    { upserts, removes } → { size, merged, memories }
+    if (pathname === '/v1/memory/list' && req.method === 'GET') {
+      return sendJson(res, 200, { ok: true, size: memoryStore.size, memories: memoryStore.list() });
+    }
+    if (pathname === '/v1/memory/recall' && req.method === 'POST') {
+      try {
+        const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+        const got = memoryStore.recall({
+          text: String(body.text || ''),
+          scopes: Array.isArray(body.scopes) && body.scopes.length ? body.scopes.map(String) : ['global'],
+          limit: Number(body.limit) || 0,
+          maxChars: Number(body.maxChars) || 0,
+        });
+        return sendJson(res, 200, { ok: true, size: memoryStore.size, ...got });
+      } catch (e) {
+        return sendJson(res, 400, { error: { message: `recall failed: ${e.message}`, type: 'memory_error' } });
+      }
+    }
+    if (pathname === '/v1/memory/remember' && req.method === 'POST') {
+      try {
+        const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+        const out = memoryStore.remember({
+          text: String(body.text || ''),
+          kind: body.kind ? String(body.kind) : 'fact',
+          scope: body.scope ? String(body.scope) : 'global',
+          tags: Array.isArray(body.tags) ? body.tags.map(String) : [],
+          // WHO PROPOSED IT, always recorded. There is no confirm dialog on a CLI, so
+          // attribution plus an inspectable list in the extension IS the accountability —
+          // see the MCP server's note on why writes are allowed but never anonymous.
+          source: {
+            via: String(body.source?.via || 'mcp'),
+            surface: String(body.source?.surface || 'mcp'),
+            agent: String(body.source?.agent || ''),
+            ref: String(body.source?.ref || ''),
+          },
+        });
+        return sendJson(res, 200, { ok: true, action: out.action, record: out.record, replaced: out.replaces || null, size: memoryStore.size });
+      } catch (e) {
+        return sendJson(res, 400, { error: { message: e.message, type: 'memory_error' } });
+      }
+    }
+    if (pathname === '/v1/memory/forget' && req.method === 'POST') {
+      try {
+        const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+        const { removed } = memoryStore.forget(String(body.query || ''));
+        return sendJson(res, 200, { ok: true, removed, size: memoryStore.size });
+      } catch (e) {
+        return sendJson(res, 400, { error: { message: e.message, type: 'memory_error' } });
+      }
+    }
+    if (pathname === '/v1/memory/sync' && req.method === 'POST') {
+      try {
+        const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+        const out = memoryStore.bulk({
+          upserts: Array.isArray(body.upserts) ? body.upserts : [],
+          removes: Array.isArray(body.removes) ? body.removes : [],
+        });
+        // The full set comes BACK, so one round trip is the whole two-way merge: the client
+        // pushes what it has and receives what the agents wrote. Convergent because both
+        // sides reconcile with the same function.
+        return sendJson(res, 200, { ok: true, ...out, memories: memoryStore.list() });
+      } catch (e) {
+        return sendJson(res, 400, { error: { message: `memory sync failed: ${e.message}`, type: 'memory_error' } });
+      }
+    }
+    if (pathname === '/v1/memory/clear' && req.method === 'POST') {
+      return sendJson(res, 200, { ok: true, dropped: memoryStore.clear(), size: memoryStore.size });
+    }
+
     if (pathname === '/v1/history/clear' && req.method === 'POST') {
       const dropped = historyStore.clear();
       return sendJson(res, 200, { ok: true, dropped, size: historyStore.size });
@@ -616,6 +702,38 @@ export function createGateway(cfg = loadConfig()) {
         return sendJson(res, 400, { error: { message: `search failed: ${e.message}`, type: 'search_error' } });
       }
     }
+    // SMART SEARCH — one round trip that expands the question into several complementary
+    // queries, runs them all, and RRF-fuses the results. A natural-language question is a
+    // poor BM25 query; asking three ways and fusing beats asking once, and doing it here
+    // means the agent pays one call instead of probing repeatedly.
+    if (pathname === '/v1/history/smart-search' && req.method === 'POST') {
+      try {
+        const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+        const question = String(body.question || body.query || '');
+        // The agent's own formulations lead (it understands the domain); planQueries adds
+        // deterministic variants and dedupes.
+        const queries = planQueries(question, {
+          extra: Array.isArray(body.queries) ? body.queries.map(String) : [],
+          max: Math.min(6, Math.max(1, Number(body.maxQueries) || 4)),
+        });
+        const filters = {
+          type: body.type ? String(body.type) : null,
+          since: body.since != null ? Number(body.since) : null,
+          before: body.before != null ? Number(body.before) : null,
+        };
+        const perQuery = Math.min(30, Math.max(5, Number(body.limit) || 10) * 2);
+        const results = await multiSearch(
+          queries,
+          (q) => historyStore.search(q, { limit: perQuery, ...filters }),
+          { limit: Math.min(50, Math.max(1, Number(body.limit) || 10)) },
+        );
+        return sendJson(res, 200, {
+          ok: true, size: historyStore.size, newest: historyStore.newest, queries, results,
+        });
+      } catch (e) {
+        return sendJson(res, 400, { error: { message: `smart search failed: ${e.message}`, type: 'search_error' } });
+      }
+    }
     // Graph navigation — records most connected to a given one.
     if (pathname === '/v1/history/related' && req.method === 'GET') {
       const id = String(url.searchParams.get('id') || '');