@llmnesia/mcp 0.1.15 → 0.2.0

package/README.md

@@ -78,8 +78,7 @@ search, list, and read the local corpus but cannot modify it.
 The future Claude Directory listing is a convenience distribution route, not a
 dependency for the general LLMnesia release. It will replace this one manual
 Claude step with Claude's own in-app install button if Anthropic selects the
-extension. See [`docs/CLAUDE_DESKTOP_RELEASE_PLAN.md`](../docs/CLAUDE_DESKTOP_RELEASE_PLAN.md)
-for the release and directory-submission plan.
+extension.
 
 The `install` command is the approval to perform those setup steps. It does not
 interrupt setup with a separate prompt for every detected app, and it never
@@ -128,7 +127,7 @@ If nothing has written to the corpus yet, search results will be empty.
 
 ## Tools
 
-Once registered, your MCP client gains six tools over the corpus:
+Once registered, your MCP client gains seven tools over the corpus:
 
 | Tool | Purpose |
 | --- | --- |
@@ -138,6 +137,14 @@ Once registered, your MCP client gains six tools over the corpus:
 | `list_recent` | List the most recently updated conversations with title, summary, and platform. |
 | `corpus_status` | Report when the corpus last received data and how many conversations it holds. Use this when an expected conversation cannot be found, to tell a genuinely missing chat apart from a corpus that has stopped receiving updates. |
 | `save_conversation` | Add or update a conversation in the corpus, so MCP is also an ingestion route. |
+| `save_memory` | Record a durable fact (a decision, preference, or correction) worth carrying into later chats. Stored turned off until the user reviews and enables it. |
+
+### Read-only mode (`LLMNESIA_READ_ONLY`)
+
+The Claude Desktop extension (`.mcpb`) ships with `LLMNESIA_READ_ONLY=1`, which
+disables the two write tools (`save_conversation` and `save_memory`) so that
+ordinary history searches run without a per-call approval prompt. The general
+npm install exposes all seven tools.
 
 Search and list results carry a `corpus` block saying when the corpus last
 received data — check it before concluding a chat does not exist.

package/dist/{chunk-C7ZUT5N7.js → chunk-53KPHHH2.js}

@@ -3,7 +3,7 @@ import { createRequire as __llmnesiaCreateRequire } from "node:module";
 const require = __llmnesiaCreateRequire(import.meta.url);
 import {
   VERSION
-} from "./chunk-YYNCL7SQ.js";
+} from "./chunk-ACIWPSVH.js";
 
 // src/config.ts
 import { readFileSync } from "fs";
@@ -35,13 +35,26 @@ function expandHome(p) {
   return resolve(p);
 }
 
-// src/corpus.ts
-import { promises as fs } from "fs";
-import { dirname, join as join3 } from "path";
-
 // src/paths.ts
 import { join as join2 } from "path";
+import { readdir } from "fs/promises";
 import { createHash } from "crypto";
+var INDEX_FORMAT_VERSION = 2;
+function indexDbFilename(version) {
+  return version === 1 ? "llmnesia.db" : `llmnesia-v${version}.db`;
+}
+async function staleIndexFiles(dir) {
+  const keep = indexDbFilename(INDEX_FORMAT_VERSION);
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return [];
+  }
+  return entries.filter(
+    (name) => /^llmnesia(-v\d+)?\.db$/.test(name) && name !== keep
+  );
+}
 var CorpusPaths = class {
   constructor(root) {
     this.root = root;
@@ -59,11 +72,14 @@ var CorpusPaths = class {
   get conversationsDir() {
     return join2(this.root, "conversations");
   }
+  get memoriesDir() {
+    return join2(this.root, "memories");
+  }
   get indexDir() {
     return join2(this.root, "index");
   }
   get indexDbFile() {
-    return join2(this.indexDir, "llmnesia.db");
+    return join2(this.indexDir, indexDbFilename(INDEX_FORMAT_VERSION));
   }
   /** Directory holding a platform's conversation JSON files. */
   platformDir(platform) {
@@ -73,6 +89,14 @@ var CorpusPaths = class {
   conversationFile(platform, docId) {
     return join2(this.platformDir(platform), `${slugifyDocId(docId)}.json`);
   }
+  /**
+   * Absolute path to the JSON file backing a given memoryId. Memories are flat
+   * rather than partitioned by platform: they are user-curated and few, and a
+   * memory is not owned by any one platform the way a conversation is.
+   */
+  memoryFile(memoryId) {
+    return join2(this.memoriesDir, `${slugifyDocId(memoryId)}.json`);
+  }
 };
 var SLUG_MAX = 120;
 function slugifyDocId(docId) {
@@ -89,6 +113,10 @@ function safeSegment(value) {
   return cleaned.length > 0 ? cleaned : "unknown";
 }
 
+// src/corpus.ts
+import { promises as fs } from "fs";
+import { dirname, join as join3 } from "path";
+
 // src/serialize.ts
 function canonicalizeConversation(record) {
   return {
@@ -96,6 +124,31 @@ function canonicalizeConversation(record) {
     messages: [...record.messages].sort((a, b) => a.msgIndex - b.msgIndex).map(canonicalMessageDoc)
   };
 }
+function canonicalizeMemory(memory) {
+  const out = {
+    memoryId: memory.memoryId,
+    kind: memory.kind,
+    label: memory.label,
+    text: memory.text,
+    source: memory.source
+  };
+  assignIfDefined(out, "sourceDocId", memory.sourceDocId);
+  assignIfDefined(out, "sourcePlatform", memory.sourcePlatform);
+  assignIfDefined(out, "sourceUrl", memory.sourceUrl);
+  assignIfDefined(out, "sourceTitle", memory.sourceTitle);
+  assignIfDefined(out, "sourceMsgStart", memory.sourceMsgStart);
+  assignIfDefined(out, "sourceMsgEnd", memory.sourceMsgEnd);
+  out.pinned = memory.pinned;
+  out.enabled = memory.enabled;
+  if (memory.tags && memory.tags.length > 0) {
+    out.tags = [...memory.tags].sort();
+  }
+  out.createdAt = memory.createdAt;
+  out.updatedAt = memory.updatedAt;
+  assignIfDefined(out, "lastUsedAt", memory.lastUsedAt);
+  assignIfDefined(out, "useCount", memory.useCount);
+  return out;
+}
 function canonicalConversationDoc(c) {
   const out = {
     docId: c.docId,
@@ -171,10 +224,12 @@ var Corpus = class {
   /** Create the directory skeleton and meta.json if absent. Idempotent. */
   async init() {
     await fs.mkdir(this.paths.conversationsDir, { recursive: true, mode: DIR_MODE });
+    await fs.mkdir(this.paths.memoriesDir, { recursive: true, mode: DIR_MODE });
     await fs.mkdir(this.paths.processedDir, { recursive: true, mode: DIR_MODE });
     await fs.mkdir(this.paths.indexDir, { recursive: true, mode: DIR_MODE });
     await hardenDir(this.paths.root);
     await hardenDir(this.paths.conversationsDir);
+    await hardenDir(this.paths.memoriesDir);
     await hardenDir(this.paths.inboxDir);
     await hardenDir(this.paths.processedDir);
     await hardenDir(this.paths.indexDir);
@@ -257,6 +312,60 @@ var Corpus = class {
     }
     return null;
   }
+  /**
+   * Write an agent-authored memory, keyed on memoryId.
+   *
+   * The semantics differ from {@link upsert} on purpose. A memoryId is a
+   * content hash, so an existing file at that id already holds this exact
+   * memory: re-writing it would only churn the timestamps, and it would stamp
+   * `enabled: false` back over a memory the user had reviewed and turned on.
+   * So an existing record wins and the write is skipped.
+   *
+   * A record whose `source` is not "agent" is refused outright rather than
+   * skipped: a captured conversation or a memory the user wrote by hand must be
+   * untouchable from the agent write path, and the caller should hear about it
+   * rather than believe its write landed.
+   */
+  async upsertMemory(memory) {
+    return this.enqueueWrite(async () => {
+      const canonical = canonicalizeMemory(memory);
+      const file = this.paths.memoryFile(canonical.memoryId);
+      const existing = await readJsonIfExists(file);
+      if (existing) {
+        if (existing.source !== "agent") {
+          return { memoryId: canonical.memoryId, outcome: "refused" };
+        }
+        return { memoryId: canonical.memoryId, outcome: "skipped" };
+      }
+      await fs.mkdir(dirname(file), { recursive: true, mode: DIR_MODE });
+      await writeFileAtomic(file, `${JSON.stringify(canonical, null, 2)}
+`);
+      return { memoryId: canonical.memoryId, outcome: "created" };
+    });
+  }
+  /** Read a memory by memoryId, or null when it has never been written. */
+  async getMemory(memoryId) {
+    const record = await readJsonIfExists(this.paths.memoryFile(memoryId));
+    return record && record.memoryId === memoryId ? record : null;
+  }
+  /** Async-iterate every stored memory (used by the index rebuild). */
+  async *iterateMemories() {
+    let files;
+    try {
+      files = await fs.readdir(this.paths.memoriesDir);
+    } catch {
+      return;
+    }
+    for (const name of files.sort()) {
+      if (!name.endsWith(".json")) {
+        continue;
+      }
+      const record = await readJsonIfExists(join3(this.paths.memoriesDir, name));
+      if (record?.memoryId) {
+        yield record;
+      }
+    }
+  }
   /** Platform subdirectory names under conversations/. */
   async listPlatforms() {
     try {
@@ -581,11 +690,22 @@ function hardenDbFile(dbPath) {
   } catch {
   }
 }
-var INDEX_FORMAT_VERSION = 1;
 var TITLE_ROW_INDEX = -1;
 var TITLE_ROLE = "title";
 var DEFAULT_LIMIT = 10;
 var SNIPPET_TOKENS = 12;
+var META_SQL = `
+CREATE TABLE IF NOT EXISTS index_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+var DROP_DERIVED_SQL = `
+DROP TABLE IF EXISTS conversations;
+DROP TABLE IF EXISTS messages_fts;
+DROP TABLE IF EXISTS memories;
+DROP TABLE IF EXISTS memories_fts;
+`;
 var SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS index_meta (
   key TEXT PRIMARY KEY,
@@ -601,7 +721,9 @@ CREATE TABLE IF NOT EXISTS conversations (
   updatedAt INTEGER NOT NULL,
   messageCount INTEGER NOT NULL,
   preview TEXT NOT NULL,
-  pinned INTEGER NOT NULL
+  pinned INTEGER NOT NULL,
+  accountId TEXT,
+  accountLabel TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_conversations_platform ON conversations(platform);
 CREATE INDEX IF NOT EXISTS idx_conversations_createdAt ON conversations(createdAt);
@@ -613,15 +735,41 @@ CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
   text,
   tokenize = 'porter unicode61'
 );
+
+CREATE TABLE IF NOT EXISTS memories (
+  memoryId TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  label TEXT NOT NULL,
+  text TEXT NOT NULL,
+  source TEXT NOT NULL,
+  pinned INTEGER NOT NULL,
+  enabled INTEGER NOT NULL,
+  createdAt INTEGER NOT NULL,
+  updatedAt INTEGER NOT NULL
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  memoryId UNINDEXED,
+  label,
+  text,
+  tokenize = 'porter unicode61'
+);
 `;
 var SearchIndex = class {
   db;
   stmts;
+  /** Whether the on-disk index was a stale format version when it was opened. */
+  staleOnOpen;
   constructor(dbPath) {
     hardenDbFile(dbPath);
     this.db = new (loadSqlite()).DatabaseSync(dbPath);
     this.db.exec("PRAGMA journal_mode = WAL");
     this.db.exec("PRAGMA foreign_keys = OFF");
+    this.db.exec(META_SQL);
+    this.staleOnOpen = this.getMeta("format_version") !== String(INDEX_FORMAT_VERSION);
+    if (this.staleOnOpen) {
+      this.db.exec(DROP_DERIVED_SQL);
+    }
     this.db.exec(SCHEMA_SQL);
     this.setMeta("format_version", String(INDEX_FORMAT_VERSION));
     this.stmts = {
@@ -632,21 +780,35 @@ var SearchIndex = class {
       deleteConversation: this.db.prepare("DELETE FROM conversations WHERE docId = ?"),
       insertConversation: this.db.prepare(
         `INSERT INTO conversations
-           (docId, platform, title, url, createdAt, updatedAt, messageCount, preview, pinned)
-         VALUES (@docId, @platform, @title, @url, @createdAt, @updatedAt, @messageCount, @preview, @pinned)`
+           (docId, platform, title, url, createdAt, updatedAt, messageCount, preview, pinned, accountId, accountLabel)
+         VALUES (@docId, @platform, @title, @url, @createdAt, @updatedAt, @messageCount, @preview, @pinned, @accountId, @accountLabel)`
+      ),
+      deleteMemoryFts: this.db.prepare("DELETE FROM memories_fts WHERE memoryId = ?"),
+      insertMemoryFts: this.db.prepare(
+        "INSERT INTO memories_fts (memoryId, label, text) VALUES (?, ?, ?)"
+      ),
+      deleteMemory: this.db.prepare("DELETE FROM memories WHERE memoryId = ?"),
+      insertMemory: this.db.prepare(
+        `INSERT INTO memories
+           (memoryId, kind, label, text, source, pinned, enabled, createdAt, updatedAt)
+         VALUES (@memoryId, @kind, @label, @text, @source, @pinned, @enabled, @createdAt, @updatedAt)`
       )
     };
   }
-  /** True when the stored format version is missing or stale — caller rebuilds. */
+  /** True when the stored format version was missing or stale — caller rebuilds. */
   needsRebuild() {
-    const stored = this.getMeta("format_version");
-    return stored !== String(INDEX_FORMAT_VERSION);
+    return this.staleOnOpen;
   }
   /** Number of indexed conversations. */
   count() {
     const row = this.db.prepare("SELECT COUNT(*) AS n FROM conversations").get();
     return row.n;
   }
+  /** Number of indexed memories. */
+  countMemories() {
+    const row = this.db.prepare("SELECT COUNT(*) AS n FROM memories").get();
+    return row.n;
+  }
   /** Most-recently-updated conversations (metadata only), newest first. */
   listRecent(n) {
     return this.listConversations(n, "recent");
@@ -656,10 +818,17 @@ var SearchIndex = class {
     const limit = Math.max(1, n);
     const orderBy = sort === "oldest" ? "createdAt ASC, updatedAt ASC" : sort === "newest" ? "createdAt DESC, updatedAt DESC" : "updatedAt DESC, createdAt DESC";
     const rows = this.db.prepare(
-      `SELECT docId, platform, title, url, createdAt, updatedAt, messageCount, preview, pinned
+      `SELECT docId, platform, title, url, createdAt, updatedAt, messageCount, preview, pinned,
+                accountId, accountLabel
          FROM conversations ORDER BY ${orderBy} LIMIT ?`
     ).all(limit);
-    return rows.map((r) => ({ ...r, pinned: r.pinned === 1 }));
+    return rows.map((r) => {
+      const { accountId, accountLabel, ...rest } = r;
+      const entry = { ...rest, pinned: r.pinned === 1 };
+      if (accountId) entry.accountId = accountId;
+      if (accountLabel) entry.accountLabel = accountLabel;
+      return entry;
+    });
   }
   /**
    * Run `fn` inside a transaction, rolling back if it throws. node:sqlite has
@@ -681,6 +850,9 @@ var SearchIndex = class {
   upsertConversation(record) {
     this.transaction(() => this.writeRecord(record));
   }
+  upsertMemory(memory) {
+    this.transaction(() => this.writeMemory(memory));
+  }
   removeConversation(docId) {
     this.transaction(() => {
       this.stmts.deleteFts.run(docId);
@@ -694,19 +866,25 @@ var SearchIndex = class {
    */
   async rebuildFrom(corpus) {
     this.db.exec("DELETE FROM messages_fts; DELETE FROM conversations;");
+    this.db.exec("DELETE FROM memories_fts; DELETE FROM memories;");
     let conversations = 0;
+    let memories = 0;
     this.db.exec("BEGIN");
     try {
       for await (const record of corpus.iterate()) {
         this.writeRecord(record);
         conversations += 1;
       }
+      for await (const memory of corpus.iterateMemories()) {
+        this.writeMemory(memory);
+        memories += 1;
+      }
       this.db.exec("COMMIT");
     } catch (err) {
       this.db.exec("ROLLBACK");
       throw err;
     }
-    return { conversations };
+    return { conversations, memories };
   }
   // Replace a conversation's index rows. Caller supplies the transaction (the
   // transaction() helper for single upserts, or rebuildFrom's manual one).
@@ -732,7 +910,32 @@ var SearchIndex = class {
       updatedAt: conversation.updatedAt ?? conversation.contentUpdatedAt ?? 0,
       messageCount: conversation.messageCount ?? messages.length,
       preview: conversation.preview ?? "",
-      pinned: conversation.pinned ? 1 : 0
+      pinned: conversation.pinned ? 1 : 0,
+      accountId: conversation.accountId ?? null,
+      accountLabel: conversation.accountLabel ?? null
+    });
+  }
+  // Replace a memory's index rows. Caller supplies the transaction, as with
+  // writeRecord. Memories live in their own tables rather than in messages_fts:
+  // a memory is not a turn in a conversation, and mixing them would let a
+  // stored note answer a question about what the user actually said.
+  writeMemory(memory) {
+    this.stmts.deleteMemoryFts.run(memory.memoryId);
+    this.stmts.deleteMemory.run(memory.memoryId);
+    const searchable = [memory.label, memory.text].filter(Boolean).join("\n");
+    if (searchable.trim()) {
+      this.stmts.insertMemoryFts.run(memory.memoryId, memory.label, memory.text);
+    }
+    this.stmts.insertMemory.run({
+      memoryId: memory.memoryId,
+      kind: memory.kind,
+      label: memory.label,
+      text: memory.text,
+      source: memory.source,
+      pinned: memory.pinned ? 1 : 0,
+      enabled: memory.enabled ? 1 : 0,
+      createdAt: memory.createdAt,
+      updatedAt: memory.updatedAt
     });
   }
   search(query, filters = {}) {
@@ -763,7 +966,7 @@ var SearchIndex = class {
     const sql = `
       SELECT
         c.docId, c.platform, c.title, c.url, c.createdAt, c.updatedAt,
-        c.messageCount, c.preview, c.pinned,
+        c.messageCount, c.preview, c.pinned, c.accountId, c.accountLabel,
         m.msgIndex AS msgIndex, m.role AS role,
         snippet(messages_fts, 3, '[', ']', '\u2026', ${SNIPPET_TOKENS}) AS snippet,
         bm25(messages_fts) AS bm25
@@ -781,7 +984,7 @@ var SearchIndex = class {
         continue;
       }
       seen.add(row.docId);
-      hits.push({
+      const hit = {
         docId: row.docId,
         platform: row.platform,
         title: row.title,
@@ -796,7 +999,10 @@ var SearchIndex = class {
         snippet: row.snippet,
         matchRole: normalizeMatchRole(row.role),
         matchMsgIndex: row.msgIndex
-      });
+      };
+      if (row.accountId) hit.accountId = row.accountId;
+      if (row.accountLabel) hit.accountLabel = row.accountLabel;
+      hits.push(hit);
       if (hits.length >= limit) {
         break;
       }
@@ -817,7 +1023,7 @@ var SearchIndex = class {
 async function openSearchIndex(corpus, options = {}) {
   await corpus.init();
   const index = new SearchIndex(corpus.paths.indexDbFile);
-  if (options.autoBuild !== false && (index.needsRebuild() || index.count() === 0)) {
+  if (options.autoBuild !== false && (index.needsRebuild() || index.count() === 0 && index.countMemories() === 0)) {
     await index.rebuildFrom(corpus);
   }
   return index;
@@ -848,7 +1054,7 @@ function normalizeMatchRole(role) {
 }
 
 // src/runtimeInstall.ts
-import { cp, mkdir, readdir, rename, rm, writeFile } from "fs/promises";
+import { cp, mkdir, readdir as readdir2, rename, rm, writeFile } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir as homedir2 } from "os";
 import { dirname as dirname2, join as join5 } from "path";
@@ -879,7 +1085,7 @@ async function installRuntime(options = {}) {
   await rm(backupDir, { recursive: true, force: true });
   await mkdir(stagingDir, { recursive: true });
   try {
-    for (const name of await readdir(sourceDir)) {
+    for (const name of await readdir2(sourceDir)) {
       await cp(join5(sourceDir, name), join5(stagingDir, name), { recursive: true });
     }
     await writeFile(
@@ -1138,6 +1344,7 @@ function describeOutcome(outcome) {
 
 export {
   resolveCorpusDir,
+  staleIndexFiles,
   Corpus,
   ingestFile,
   pendingInboxFiles,

package/dist/{chunk-YYNCL7SQ.js → chunk-ACIWPSVH.js}

@@ -38,7 +38,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/version.ts
-var VERSION = true ? "0.1.15" : "0.0.0-dev";
+var VERSION = true ? "0.2.0" : "0.0.0-dev";
 
 export {
   __require,

package/dist/{cli-BQZPGQQX.js → cli-VB4QKSGH.js}

@@ -12,14 +12,15 @@ import {
   openSearchIndex,
   resolveCorpusDir,
   runtimeBinDir,
+  staleIndexFiles,
   uninstallRuntime
-} from "./chunk-C7ZUT5N7.js";
+} from "./chunk-53KPHHH2.js";
 import {
   VERSION,
   __commonJS,
   __require,
   __toESM
-} from "./chunk-YYNCL7SQ.js";
+} from "./chunk-ACIWPSVH.js";
 
 // ../node_modules/isexe/windows.js
 var require_windows = __commonJS({
@@ -524,6 +525,7 @@ var require_cross_spawn = __commonJS({
 
 // src/cli.ts
 import { createInterface } from "readline/promises";
+import { join as join6 } from "path";
 
 // ../packages/native-host/install.mjs
 import { execFile } from "child_process";
@@ -4032,6 +4034,16 @@ ${platforms}
       } finally {
         index.close();
       }
+      const stale = await staleIndexFiles(corpus.paths.indexDir);
+      for (const name of stale) {
+        await deleteIndexDb(join6(corpus.paths.indexDir, name));
+      }
+      if (stale.length > 0) {
+        process.stdout.write(
+          `Removed ${stale.length} index file(s) from older versions: ${stale.join(", ")}
+`
+        );
+      }
       return 0;
     }
     case "search": {

package/dist/cli.js

@@ -3,7 +3,7 @@ import { createRequire as __llmnesiaCreateRequire } from "node:module";
 const require = __llmnesiaCreateRequire(import.meta.url);
 import {
   VERSION
-} from "./chunk-YYNCL7SQ.js";
+} from "./chunk-ACIWPSVH.js";
 
 // src/nodeDownload.ts
 var NODE_DOWNLOAD_URLS = {
@@ -141,7 +141,7 @@ async function bootstrap() {
     await guideUnsupportedNodeVersion(process.versions.node);
     return 1;
   }
-  const { main } = await import("./cli-BQZPGQQX.js");
+  const { main } = await import("./cli-VB4QKSGH.js");
   return main();
 }
 bootstrap().then((code) => {

package/dist/llmnesia-claude-host.mjs

@@ -18,11 +18,17 @@
 // without ~/.llmnesia/config.json this host is exactly as read-only as it
 // has always been for plain session indexing.
 //
-// Protocol v2 (extension → host). v1 was Claude-Code-only: `list` carried no
+// Protocol v3 (extension → host). v1 was Claude-Code-only: `list` carried no
 // `source` and `get` took a bare sessionId. Both remain accepted, so an
 // extension older than this host keeps working; an extension NEWER than the
 // host detects v1 from the pong and syncs Claude Code only.
-//   { cmd: "ping" }                    → { type: "pong", version: 2 }
+//
+// v3 adds `listMemories`, the RC-03 reverse channel. A v2 host answers it with
+// `{ type: "error", error: "unknown command: listMemories" }` and the extension
+// treats that as "nothing to fetch", so the version is informational: hosts are
+// installed out of band and an extension upgraded ahead of its host is the
+// ordinary case, not a fault.
+//   { cmd: "ping" }                    → { type: "pong", version: 3 }
 //   { cmd: "list" }                    → { type: "list", sessions:
 //                                          [{source, sessionId, mtime, project?, title?}] }
 //   { cmd: "get", source, sessionId }  → one or more { type: "chunk", sessionId, seq, total, data }
@@ -33,6 +39,11 @@
 //     seq, total, data }               → { type: "chunkAck", seq }
 //                                        (writes <root>/inbox/<filename> once
 //                                        every chunk 0..total-1 has arrived)
+//   { cmd: "listMemories" }            → { type: "memories", present,
+//                                          memories: [MemoryDoc], skipped }
+//                                        (reads <root>/memories/*.json; the
+//                                        only read path that touches the
+//                                        corpus rather than a session root)
 //
 // The extension never names a path in either direction: it asks for a
 // (source, sessionId) pair and the host resolves it against its own roots. That
@@ -42,7 +53,13 @@ import { chmod, mkdir, readdir, readFile, rename, stat, writeFile } from "node:f
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-const PROTOCOL_VERSION = 2;
+// 3 adds `listMemories` (RC-03). A v2 host answers that command with
+// `{ type: "error", error: "unknown command: listMemories" }`, which the
+// extension treats as "this host is too old, there is nothing to fetch" — so
+// bumping this is informational, not a gate. Do not make it a gate: hosts are
+// installed out of band and a version check would strand every user who
+// upgraded the extension first.
+const PROTOCOL_VERSION = 3;
 const PROJECTS_DIR = join(homedir(), ".claude", "projects");
 const CONFIG_FILE = join(homedir(), ".llmnesia", "config.json");
 // Codex's home, resolved at install time (--codex-home > CODEX_HOME > ~/.codex)
@@ -69,6 +86,12 @@ const MAX_PUT_TRANSFER_CHARS = 64 * 1024 * 1024;
 const MAX_PENDING_WRITE_CHARS = 64 * 1024 * 1024;
 const MAX_PENDING_WRITES = 8;
 const PENDING_WRITE_TTL_MS = 5 * 60 * 1000;
+// RC-03 reverse channel. Memories are one small JSON object each and exist to
+// be reviewed by a person, so a corpus holding thousands of them is a bug
+// upstream, not a case to stream. Capping the reply keeps it inside native
+// messaging's ~1 MB per-message ceiling without a chunking protocol.
+const MAX_MEMORY_FILE_CHARS = 128 * 1024;
+const MAX_MEMORIES_PER_REPLY = 200;
 
 function send(message) {
   const body = Buffer.from(JSON.stringify(message), "utf8");
@@ -355,6 +378,60 @@ async function handlePutChunk(message) {
   send({ type: "chunkAck", seq });
 }
 
+/**
+ * RC-03: read agent-written memories out of `<corpusRoot>/memories/*.json`.
+ *
+ * This is a different read source from `list`/`get`, which serve session
+ * transcripts from ~/.claude/projects and ~/.codex and never touch the corpus.
+ * The layout mirrors companion/src/corpus.ts `iterateMemories`: one JSON object
+ * per file, named by a slug of its memoryId.
+ *
+ * Tolerant by design, matching the companion's own reader: a single unreadable
+ * or malformed file must not deny the user every other memory waiting for
+ * review. Skipped files are counted so the extension can say something honest
+ * rather than silently under-reporting.
+ */
+async function readCorpusMemories(corpusRoot) {
+  const dir = join(corpusRoot, "memories");
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch {
+    // No memories directory yet. Not an error: nothing has written one.
+    return { memories: [], skipped: 0 };
+  }
+
+  const memories = [];
+  let skipped = 0;
+  for (const name of names.sort()) {
+    if (!name.endsWith(".json")) {
+      continue;
+    }
+    if (memories.length >= MAX_MEMORIES_PER_REPLY) {
+      skipped += 1;
+      continue;
+    }
+    try {
+      const raw = await readFile(join(dir, name), "utf8");
+      if (raw.length > MAX_MEMORY_FILE_CHARS) {
+        skipped += 1;
+        continue;
+      }
+      const record = JSON.parse(raw);
+      // memoryId is the identity the extension dedupes on. Without it the
+      // record cannot be ingested safely, so drop it rather than invent one.
+      if (record && typeof record === "object" && typeof record.memoryId === "string" && record.memoryId) {
+        memories.push(record);
+      } else {
+        skipped += 1;
+      }
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { memories, skipped };
+}
+
 async function handle(message) {
   if (!message || typeof message !== "object") {
     return;
@@ -376,6 +453,16 @@ async function handle(message) {
     await handlePutChunk(message);
     return;
   }
+  if (message.cmd === "listMemories") {
+    const config = await loadConfig();
+    if (!config?.corpusRoot) {
+      send({ type: "memories", present: false, memories: [], skipped: 0 });
+      return;
+    }
+    const { memories, skipped } = await readCorpusMemories(config.corpusRoot);
+    send({ type: "memories", present: true, memories, skipped });
+    return;
+  }
   if (message.cmd === "list") {
     const sessions = await listSessions();
     send({ type: "list", sessions: sessions.map(({ path, ...rest }) => rest) });

package/dist/mcp.js

@@ -9,13 +9,13 @@ import {
   pendingInboxFiles,
   resolveCorpusDir,
   scheduleSelfUpdate
-} from "./chunk-C7ZUT5N7.js";
+} from "./chunk-53KPHHH2.js";
 import {
   VERSION,
   __commonJS,
   __export,
   __toESM
-} from "./chunk-YYNCL7SQ.js";
+} from "./chunk-ACIWPSVH.js";
 
 // ../node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS({
@@ -21248,24 +21248,176 @@ function sha1(value) {
   return createHash("sha1").update(value).digest("hex");
 }
 
+// src/memory.ts
+import { createHash as createHash2 } from "crypto";
+var MEMORY_KINDS = ["fact", "preference", "project", "profile"];
+var DEFAULT_MEMORY_WRITE_CAP = 10;
+var LABEL_MAX = 120;
+var TEXT_MAX = 2e3;
+var TAGS_MAX = 8;
+var TAG_MAX = 40;
+var MemoryWriteError = class extends Error {
+};
+var MemoryValidationError = class extends MemoryWriteError {
+};
+var MemoryWriteCapError = class extends MemoryWriteError {
+};
+var MemoryOverwriteRefusedError = class extends MemoryWriteError {
+};
+var saveMemorySchema = external_exports.object({
+  kind: external_exports.enum(MEMORY_KINDS).describe(
+    "What sort of memory this is. 'fact' for a durable truth, 'preference' for how the user wants things done, 'project' for context about ongoing work, 'profile' for who the user is."
+  ),
+  label: external_exports.string().describe("A short title for the review list, a few words."),
+  text: external_exports.string().describe("The memory itself: one idea, stated so it still makes sense months from now."),
+  tags: external_exports.array(external_exports.string()).optional().describe("Optional short tags for grouping."),
+  sourceDocId: external_exports.string().optional().describe("The id of the conversation this came from, when it came from one."),
+  sourcePlatform: external_exports.string().optional().describe("The platform of the source conversation."),
+  sourceUrl: external_exports.string().optional().describe("Link back to where this came from."),
+  sourceTitle: external_exports.string().optional().describe("Title of the source conversation."),
+  sourceMsgStart: external_exports.number().int().optional().describe("First message index this came from."),
+  sourceMsgEnd: external_exports.number().int().optional().describe("Last message index this came from.")
+});
+function parseSaveMemoryInput(payload) {
+  const parsed = saveMemorySchema.safeParse(payload);
+  if (!parsed.success) {
+    throw new MemoryValidationError(describeIssues(parsed.error));
+  }
+  const input = parsed.data;
+  const problems = [];
+  const label = collapse(input.label);
+  const text = collapse(input.text);
+  if (!label) {
+    problems.push("label must not be empty: give the memory a short title, a few words");
+  } else if (label.length > LABEL_MAX) {
+    problems.push(`label is ${label.length} characters; shorten it to ${LABEL_MAX} or fewer`);
+  }
+  if (!text) {
+    problems.push("text must not be empty: this is the memory itself, so it has to say something");
+  } else if (text.length > TEXT_MAX) {
+    problems.push(
+      `text is ${text.length} characters; a memory holds one idea, so shorten it to ${TEXT_MAX} or fewer, or split it into separate memories`
+    );
+  }
+  const tags = normalizeTags(input.tags);
+  if (tags.length > TAGS_MAX) {
+    problems.push(`there are ${tags.length} tags; keep it to ${TAGS_MAX} or fewer`);
+  }
+  if (tags.some((tag) => tag.length > TAG_MAX)) {
+    problems.push(`each tag must be ${TAG_MAX} characters or fewer`);
+  }
+  if (problems.length > 0) {
+    throw new MemoryValidationError(formatProblems(problems));
+  }
+  const cleaned = { ...input, kind: input.kind, label, text };
+  if (tags.length > 0) {
+    cleaned.tags = tags;
+  } else {
+    delete cleaned.tags;
+  }
+  return cleaned;
+}
+function normalizeMemoryInput(input, now = Date.now()) {
+  const memory = {
+    memoryId: memoryIdFor(input),
+    kind: input.kind,
+    label: input.label,
+    text: input.text,
+    source: "agent",
+    pinned: false,
+    enabled: false,
+    createdAt: now,
+    updatedAt: now
+  };
+  if (input.sourceDocId) memory.sourceDocId = input.sourceDocId;
+  if (input.sourcePlatform) memory.sourcePlatform = input.sourcePlatform;
+  if (input.sourceUrl) memory.sourceUrl = input.sourceUrl;
+  if (input.sourceTitle) memory.sourceTitle = input.sourceTitle;
+  if (input.sourceMsgStart !== void 0) memory.sourceMsgStart = input.sourceMsgStart;
+  if (input.sourceMsgEnd !== void 0) memory.sourceMsgEnd = input.sourceMsgEnd;
+  if (input.tags && input.tags.length > 0) memory.tags = input.tags;
+  return memory;
+}
+function memoryIdFor(input) {
+  const basis = [input.kind, normalizeForHash(input.label), normalizeForHash(input.text)].join("\n");
+  return `agent-${createHash2("sha256").update(basis).digest("hex").slice(0, 32)}`;
+}
+function resolveMemoryWriteCap(raw = process.env.LLMNESIA_MEMORY_WRITE_CAP) {
+  if (raw === void 0 || raw.trim() === "") {
+    return DEFAULT_MEMORY_WRITE_CAP;
+  }
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return DEFAULT_MEMORY_WRITE_CAP;
+  }
+  return parsed;
+}
+function normalizeTags(tags) {
+  if (!tags) {
+    return [];
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const tag of tags) {
+    const cleaned = collapse(tag);
+    if (cleaned) {
+      seen.add(cleaned);
+    }
+  }
+  return [...seen];
+}
+function collapse(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function normalizeForHash(value) {
+  return collapse(value).toLowerCase();
+}
+function formatProblems(problems) {
+  return `save_memory could not accept this memory: ${problems.join("; ")}.`;
+}
+function describeIssues(error2) {
+  const problems = error2.issues.map((issue2) => {
+    const field = issue2.path.length > 0 ? issue2.path.join(".") : "payload";
+    if (issue2.code === "invalid_type" && issue2.received === "undefined") {
+      return `${field} is required`;
+    }
+    if (issue2.code === "invalid_type") {
+      return `${field} must be a ${issue2.expected}, not a ${issue2.received}`;
+    }
+    if (issue2.code === "invalid_enum_value") {
+      return `${field} must be one of ${MEMORY_KINDS.join(", ")}`;
+    }
+    return `${field}: ${issue2.message.toLowerCase()}`;
+  });
+  return formatProblems([...new Set(problems)]);
+}
+
 // src/service.ts
 var STALE_AFTER_HOURS = 48;
 var CompanionService = class _CompanionService {
-  constructor(corpus, index, onDrainError) {
+  constructor(corpus, index, onDrainError, memoryWriteCap) {
     this.corpus = corpus;
     this.index = index;
     this.onDrainError = onDrainError;
+    this.memoryWriteCap = memoryWriteCap;
   }
   corpus;
   index;
   onDrainError;
+  memoryWriteCap;
   // Serialize drains so concurrent reads queue behind one ingest rather than
   // racing to consume the same file (mirrors Corpus.enqueueWrite).
   refreshChain = Promise.resolve();
+  /** Memories written since this process started; the per-session cap counts these. */
+  memoriesWritten = 0;
   static async open(root, options = {}) {
     const corpus = new Corpus(root);
     const index = await openSearchIndex(corpus);
-    const service = new _CompanionService(corpus, index, options.onDrainError ?? noop);
+    const service = new _CompanionService(
+      corpus,
+      index,
+      options.onDrainError ?? noop,
+      options.memoryWriteCap ?? DEFAULT_MEMORY_WRITE_CAP
+    );
     await service.refresh();
     return service;
   }
@@ -21362,6 +21514,38 @@ var CompanionService = class _CompanionService {
     }
     return { docId: result.docId, outcome: result.outcome, messageCount: record2.messages.length };
   }
+  /**
+   * Validate, normalize, persist an agent-written memory, and index it.
+   *
+   * Throws for anything the caller should hear about and act on: a payload that
+   * is not a memory, a spent write budget, or an id already held by a record
+   * this path may not touch. A memory that was already stored is not an error,
+   * it is the dedupe working.
+   */
+  async saveMemory(payload) {
+    const input = parseSaveMemoryInput(payload);
+    const memory = normalizeMemoryInput(input);
+    if (this.memoriesWritten >= this.memoryWriteCap) {
+      throw new MemoryWriteCapError(
+        `save_memory has already stored ${this.memoryWriteCap} memories in this session, which is the limit. Every stored memory competes for the same review queue and prompt budget, so keep the rest for the next session and record only the single most durable conclusion if one is left.`
+      );
+    }
+    const result = await this.corpus.upsertMemory(memory);
+    if (result.outcome === "refused") {
+      throw new MemoryOverwriteRefusedError(
+        `save_memory will not overwrite the existing record ${result.memoryId}, which was not written by an agent. Captured conversations and memories the user wrote themselves can only be changed by the user.`
+      );
+    }
+    if (result.outcome === "created") {
+      this.memoriesWritten += 1;
+      this.index.upsertMemory(memory);
+    }
+    return {
+      memoryId: result.memoryId,
+      outcome: result.outcome,
+      remainingWrites: Math.max(0, this.memoryWriteCap - this.memoriesWritten)
+    };
+  }
   close() {
     this.index.close();
   }
@@ -21443,6 +21627,7 @@ async function runServe() {
   const root = resolveCorpusDir(process.env.LLMNESIA_CORPUS_DIR);
   const service = new LazyResource(
     () => CompanionService.open(root, {
+      memoryWriteCap: resolveMemoryWriteCap(),
       // stdout is the MCP JSON-RPC channel, so diagnostics go to stderr.
       onDrainError: (error2) => process.stderr.write(
         `llmnesia: inbox drain failed, serving the existing index: ${error2 instanceof Error ? error2.message : String(error2)}
@@ -21503,18 +21688,23 @@ async function runServe() {
       return jsonResult({
         count: hits.length,
         corpus: corpusField(status),
-        results: hits.map((h) => ({
-          id: h.docId,
-          title: h.title,
-          platform: h.platform,
-          url: h.url,
-          createdAt: h.createdAt,
-          score: Number(h.score.toFixed(4)),
-          snippet: h.snippet,
-          matchedIn: h.matchRole === "title" ? "title" : `${h.matchRole} turn ${h.matchMsgIndex}`,
-          pinned: h.pinned,
-          messageCount: h.messageCount
-        }))
+        results: hits.map((h) => {
+          const entry = {
+            id: h.docId,
+            title: h.title,
+            platform: h.platform,
+            url: h.url,
+            createdAt: h.createdAt,
+            score: Number(h.score.toFixed(4)),
+            snippet: h.snippet,
+            matchedIn: h.matchRole === "title" ? "title" : `${h.matchRole} turn ${h.matchMsgIndex}`,
+            pinned: h.pinned,
+            messageCount: h.messageCount
+          };
+          if (h.accountId) entry.accountId = h.accountId;
+          if (h.accountLabel) entry.accountLabel = h.accountLabel;
+          return entry;
+        })
       });
     })
   );
@@ -21570,15 +21760,20 @@ async function runServe() {
       return jsonResult({
         count: entries.length,
         corpus: corpusField(status),
-        conversations: entries.map((e) => ({
-          id: e.docId,
-          title: e.title,
-          platform: e.platform,
-          updatedAt: e.updatedAt,
-          messageCount: e.messageCount,
-          pinned: e.pinned,
-          summary: e.summary ?? e.preview
-        }))
+        conversations: entries.map((e) => {
+          const entry = {
+            id: e.docId,
+            title: e.title,
+            platform: e.platform,
+            updatedAt: e.updatedAt,
+            messageCount: e.messageCount,
+            pinned: e.pinned,
+            summary: e.summary ?? e.preview
+          };
+          if (e.accountId) entry.accountId = e.accountId;
+          if (e.accountLabel) entry.accountLabel = e.accountLabel;
+          return entry;
+        })
       });
     })
   );
@@ -21605,16 +21800,21 @@ async function runServe() {
         count: entries.length,
         sort: args.sort ?? "recent",
         corpus: corpusField(status),
-        conversations: entries.map((e) => ({
-          id: e.docId,
-          title: e.title,
-          platform: e.platform,
-          createdAt: e.createdAt,
-          updatedAt: e.updatedAt,
-          messageCount: e.messageCount,
-          pinned: e.pinned,
-          summary: e.summary ?? e.preview
-        }))
+        conversations: entries.map((e) => {
+          const entry = {
+            id: e.docId,
+            title: e.title,
+            platform: e.platform,
+            createdAt: e.createdAt,
+            updatedAt: e.updatedAt,
+            messageCount: e.messageCount,
+            pinned: e.pinned,
+            summary: e.summary ?? e.preview
+          };
+          if (e.accountId) entry.accountId = e.accountId;
+          if (e.accountLabel) entry.accountLabel = e.accountLabel;
+          return entry;
+        })
       });
     })
   );
@@ -21659,6 +21859,31 @@ async function runServe() {
         }
       })
     );
+    server.registerTool(
+      "save_memory",
+      {
+        title: "Save memory",
+        description: "Record one durable thing worth carrying into the user's later chats, on any platform. Write a memory when this session reached a conclusion worth keeping, when a decision was made and the reasoning behind it matters later, when an older conversation revealed a lasting fact or preference about the user or their work, or when something now known supersedes or corrects what the corpus already holds. State it so it still makes sense months from now, on its own, without this conversation to explain it. Do not use this to summarise a conversation, to save someone else's conversation, or to restate something already captured; use save_conversation for a transcript. Memories are stored turned off and stay invisible until the user reviews and enables them, so write few and write them well. Identity is a hash of the content, so saving the same memory twice stores it once.",
+        inputSchema: saveMemorySchema.shape,
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: false
+        }
+      },
+      async (args) => withService(async (service2) => {
+        try {
+          const result = await service2.saveMemory(args);
+          return jsonResult(result);
+        } catch (err) {
+          if (err instanceof MemoryWriteError) {
+            return errorResult(err.message);
+          }
+          return errorResult(`save_memory failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      })
+    );
   }
   server.server.oninitialized = () => {
     service.start();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmnesia/mcp",
-  "version": "0.1.15",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "comment:mcpName": "The MCP Registry's ownership marker: it must equal server.json's `name`, and the namespace must match how you authenticate with mcp-publisher. `com.llmnesia/...` requires DNS auth (a TXT record on llmnesia.com) — see docs/MCP_INSTALLER_BOARD.md.",

package/server.json

@@ -3,13 +3,13 @@
   "name": "com.llmnesia/mcp",
   "title": "LLMnesia",
   "description": "Search your AI chat history from Claude, Cursor, Codex, and other MCP clients.",
-  "version": "0.1.15",
+  "version": "0.2.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@llmnesia/mcp",
-      "version": "0.1.15",
+      "version": "0.2.0",
       "transport": {
         "type": "stdio"
       }