clay-server 5.2.0-beta.1 → 5.2.0-beta.3

package/lib/mate-knowledge-mate-bound.js

@@ -0,0 +1,53 @@
+// Ordinary Mate Knowledge bindings. The service supplies live validation and
+// the already-authorized scope; this module only exposes the Mate operations.
+
+function createMateBound(options) {
+  var settings = options || {};
+  var revalidate = settings.revalidate;
+  var initial = settings.initial;
+
+  function ownScope() {
+    return [revalidate().own];
+  }
+  function db(method, args) {
+    var current = revalidate();
+    if (!current.databaseService || typeof current.databaseService[method] !== "function") throw new Error("Knowledge databases are unavailable for this Mate.");
+    return current.databaseService[method](Object.assign({}, args || {}, { actor: current.actor }));
+  }
+  function text(method, args) {
+    var current = revalidate();
+    return settings.textTools[method](current.own, args || {}, current.actor);
+  }
+  return {
+    isClay: false,
+    mateId: initial.own.mateId,
+    scopeId: initial.own.scopeId,
+    listKnowledge: function (args) { return settings.listFor(ownScope(), args || {}, false); },
+    searchKnowledge: function (args) { return settings.searchFor(ownScope(), args || {}, false); },
+    readKnowledge: function (args) { return settings.readFor(ownScope(), args || {}, false); },
+    readKnowledgeDocument: function (args) { return text("read", args); },
+    createKnowledgeDocument: function (args) { return text("create", args); },
+    updateKnowledgeDocument: function (args) { return text("update", args); },
+    listKnowledgeDocumentHistory: function (args) { return text("history", args); },
+    restoreKnowledgeDocument: function (args) { return text("restore", args); },
+    listDatabases: function (args) { return db("list", args); },
+    createDatabase: function (args) { return db("create", args); },
+    readDatabase: function (args) { return db("read", args); },
+    renameDatabase: function (args) { return db("rename", args); },
+    archiveDatabase: function (args) { return db("archive", args); },
+    recoverDatabase: function (args) { return db("recover", args); },
+    updateDatabaseSchema: function (args) { return db("updateSchema", args); },
+    saveTableView: function (args) { return db("saveView", args); },
+    queryDatabase: function (args) { return db("query", args); },
+    createDatabaseRecord: function (args) { return db("createRecord", args); },
+    readDatabaseRecord: function (args) { return db("readRecord", args); },
+    updateDatabaseRecord: function (args) { return db("updateRecord", args); },
+    archiveDatabaseRecord: function (args) { return db("archiveRecord", args); },
+    recoverDatabaseRecord: function (args) { return db("recoverRecord", args); },
+    retryDatabaseSync: function (args) { return db("retryProjection", args); },
+    importDatabaseRecords: function (args) { return db("importRecords", args); },
+    readDatabaseImportProgress: function (args) { return db("readImportProgress", args); },
+  };
+}
+
+module.exports = { createMateBound: createMateBound };

package/lib/mate-knowledge-mcp-server.js

@@ -9,11 +9,17 @@
 
 var buildShape = require("./session-spawn-mcp-server").buildShape;
 var service = require("./mate-knowledge-service");
+var zod;
+try { zod = require("zod"); } catch (error) { zod = null; }
 
 var MATE_CONTRACT =
   "Your Knowledge is the durable personal and expertise context you own: what you have learned, the material you keep, and your accumulated observations. " +
   "It is yours alone. There are no other Knowledge collections available to you here, and project Logs are a separate, unrelated surface. " +
+  "Use text documents for narrative or multiline Markdown content, and databases for structured records, relationships, filters, and numeric totals. " +
   "Search it when recalling something specific would genuinely change your answer, and read only the records you actually need. " +
+  "Database list and search results are summaries for database discovery, not database row content: discover a database, read its schema, then query_database with stable field ids, typed filters, explicit sorts, bounded pagination, and totals; read individual rows by stable record id. Text search and text-document reads retain their own content and revision semantics. " +
+  "For text edits, use the returned document id and revision, reread after a conflict, and retry with the current revision. " +
+  "Treat errors as failures. A successful revision/id with indexSyncPending or projectionPending means canonical content was saved but indexing is pending: report that exact state, do not claim it is indexed, and do not blindly retry a mutation that could create a duplicate. " +
   "Do not enumerate or restate your Knowledge to the user unasked, and never reproduce whole records as filler.";
 
 var CLAY_CONTRACT =
@@ -56,24 +62,35 @@ var OPERATION = { type: "string", description: "Stable retry id formatted label_
 var FIELD = { type: "object", description: "Field with stable id, name, type, required, and type-specific options or reference target." };
 var FILTER = { type: "object", description: "Validated filter: fieldId, op, and value. Supported ops are eq, neq, contains, gt, gte, lt, lte, empty, not-empty." };
 var SORT = { type: "object", description: "Validated sort with fieldId and asc or desc direction." };
+var FIELD_SCHEMA = zod ? zod.object({ id: zod.string(), name: zod.string(), type: zod.string(), required: zod.boolean().optional(), options: zod.any().optional(), target: zod.string().optional(), targetDatabaseId: zod.string().optional(), archived: zod.boolean().optional() }) : null;
+var FILTER_SCHEMA = zod ? zod.object({ fieldId: zod.string(), op: zod.string(), value: zod.any().optional() }) : null;
+var SORT_SCHEMA = zod ? zod.object({ fieldId: zod.string(), direction: zod.enum(["asc", "desc"]) }) : null;
+var VALUES_SCHEMA = zod ? zod.record(zod.string(), zod.any()) : null;
+var VIEW_SCHEMA = zod ? zod.object({ id: zod.string(), name: zod.string(), columns: zod.array(zod.string()), filters: zod.array(FILTER_SCHEMA || zod.any()).optional(), sorts: zod.array(SORT_SCHEMA || zod.any()).optional(), archived: zod.boolean().optional() }) : null;
+var IMPORT_ROW_SCHEMA = zod ? zod.object({ sourceKey: zod.string(), sourcePayload: zod.any(), values: zod.record(zod.string(), zod.any()) }) : null;
+var IMPORT_ROW = IMPORT_ROW_SCHEMA ? { schema: IMPORT_ROW_SCHEMA, description: "Source row with sourceKey, immutable JSON sourcePayload, and typed values keyed by stable schema field id. Record references use sourceNamespace/sourceKey, including forward references within this batch." } : { type: "object", description: "Source row with sourceKey, immutable JSON sourcePayload, and typed values keyed by stable schema field id. Record references use sourceNamespace/sourceKey, including forward references within this batch." };
+var DOCUMENT_ID = { type: "string", description: "Stable document id returned by a text-document tool." };
+var DOCUMENT_REVISION = { type: "string", description: "Revision returned by the most recent text-document read or mutation; required for updates and restore." };
 
 function databaseTools(bound) {
   return [
-    { name: "list_databases", description: "List canonical Knowledge databases, including archived databases when requested, so the Mate can discover and recover them without relying on summary projection.", inputSchema: buildShape({ archived: { type: "boolean" } }, []), handler: handler(bound, "listDatabases") },
-    { name: "create_database", description: "Create a first-class database in this Mate's Knowledge. Defaults to one required title field and a Table view.", inputSchema: buildShape({ name: { type: "string" }, schema: { type: "array", items: FIELD }, operationId: OPERATION }, ["name", "operationId"]), handler: handler(bound, "createDatabase") },
-    { name: "read_database", description: "Read one Knowledge database's current schema, views, revision, and record count.", inputSchema: buildShape({ databaseId: ID, includeArchived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "readDatabase") },
+    { name: "list_databases", description: "Discover canonical Knowledge databases, including archived databases when requested. Results are database summaries only, not row content; read a chosen database before querying it.", inputSchema: buildShape({ archived: { type: "boolean" } }, []), handler: handler(bound, "listDatabases") },
+    { name: "create_database", description: "Create a first-class structured database in this Mate's Knowledge. Define typed fields for values, relationships, and numeric totals; use text documents for narrative or multiline material.", inputSchema: buildShape({ name: { type: "string" }, schema: FIELD_SCHEMA ? { schema: zod.array(FIELD_SCHEMA), description: "Typed field descriptors." } : { type: "array", items: FIELD }, operationId: OPERATION }, ["name", "operationId"]), handler: handler(bound, "createDatabase") },
+    { name: "read_database", description: "Read one discovered Knowledge database by stable database id to obtain its current schema, views, revision, and record count before querying rows.", inputSchema: buildShape({ databaseId: ID, includeArchived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "readDatabase") },
     { name: "rename_database", description: "Rename a Knowledge database with optimistic revision checking.", inputSchema: buildShape({ databaseId: ID, name: { type: "string" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "name", "expectedRevision", "operationId"]), handler: handler(bound, "renameDatabase") },
     { name: "archive_database", description: "Recoverably archive a Knowledge database.", inputSchema: buildShape({ databaseId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "expectedRevision", "operationId"]), handler: handler(bound, "archiveDatabase") },
     { name: "recover_database", description: "Recover an archived Knowledge database.", inputSchema: buildShape({ databaseId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "expectedRevision", "operationId"]), handler: handler(bound, "recoverDatabase") },
-    { name: "update_database_schema", description: "Replace the schema using stable field ids. Exactly one active title field is required; populated fields cannot be removed or change type and should be archived instead.", inputSchema: buildShape({ databaseId: ID, schema: { type: "array", items: FIELD }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "schema", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseSchema") },
-    { name: "save_table_view", description: "Create or revise a persisted Table view with selected columns, validated filters, and deterministic sorts.", inputSchema: buildShape({ databaseId: ID, view: { type: "object", description: "View with stable id, name, columns, filters, and sorts." }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "view", "expectedRevision", "operationId"]), handler: handler(bound, "saveTableView") },
-    { name: "query_database", description: "Query a bounded deterministic page of records using a saved view or explicit validated filters and sorts. Returns count and numeric sums.", inputSchema: buildShape({ databaseId: ID, viewId: ID, filters: { type: "array", items: FILTER }, sorts: { type: "array", items: SORT }, cursor: { type: "string" }, limit: { type: "number" }, archived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "queryDatabase") },
-    { name: "create_database_record", description: "Create a typed record. Values are keyed by stable field id; unknown fields and unsafe keys are rejected.", inputSchema: buildShape({ databaseId: ID, values: { type: "object" }, expectedDatabaseRevision: REVISION, operationId: OPERATION }, ["databaseId", "values", "expectedDatabaseRevision", "operationId"]), handler: handler(bound, "createDatabaseRecord") },
+    { name: "update_database_schema", description: "Replace the schema using stable field ids. Exactly one active title field is required; populated fields cannot be removed or change type and should be archived instead.", inputSchema: buildShape({ databaseId: ID, schema: FIELD_SCHEMA ? { schema: zod.array(FIELD_SCHEMA), description: "Complete typed field descriptor array." } : { type: "array", items: FIELD }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "schema", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseSchema") },
+    { name: "save_table_view", description: "Create or revise a persisted Table view with selected columns, validated filters, and deterministic sorts.", inputSchema: buildShape({ databaseId: ID, view: VIEW_SCHEMA ? { schema: VIEW_SCHEMA, description: "View with stable id, name, columns, filters, and sorts." } : { type: "object", description: "View with stable id, name, columns, filters, and sorts." }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "view", "expectedRevision", "operationId"]), handler: handler(bound, "saveTableView") },
+    { name: "query_database", description: "Query a bounded deterministic page using stable field ids, typed validated filters, explicit sorts, and a cursor. Returns only the requested rows plus count and numeric sums for the same filter scope; do not infer totals from one page.", inputSchema: buildShape({ databaseId: ID, viewId: ID, filters: FILTER_SCHEMA ? { schema: zod.array(FILTER_SCHEMA) } : { type: "array", items: FILTER }, sorts: SORT_SCHEMA ? { schema: zod.array(SORT_SCHEMA) } : { type: "array", items: SORT }, cursor: { type: "string" }, limit: { type: "number" }, archived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "queryDatabase") },
+    { name: "create_database_record", description: "Create a typed record. Values are keyed by stable field id; unknown fields and unsafe keys are rejected.", inputSchema: buildShape({ databaseId: ID, values: VALUES_SCHEMA ? { schema: VALUES_SCHEMA } : { type: "object" }, expectedDatabaseRevision: REVISION, operationId: OPERATION }, ["databaseId", "values", "expectedDatabaseRevision", "operationId"]), handler: handler(bound, "createDatabaseRecord") },
     { name: "read_database_record", description: "Read one record with its values, revision, attribution, archive state, and bounded history.", inputSchema: buildShape({ databaseId: ID, recordId: ID }, ["databaseId", "recordId"]), handler: handler(bound, "readDatabaseRecord") },
-    { name: "update_database_record", description: "Update selected typed values using the record revision. Edits to other fields made since a prior save are not overwritten.", inputSchema: buildShape({ databaseId: ID, recordId: ID, values: { type: "object" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "values", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseRecord") },
+    { name: "update_database_record", description: "Update selected typed values using the record revision. Edits to other fields made since a prior save are not overwritten.", inputSchema: buildShape({ databaseId: ID, recordId: ID, values: VALUES_SCHEMA ? { schema: VALUES_SCHEMA } : { type: "object" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "values", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseRecord") },
     { name: "archive_database_record", description: "Recoverably archive one record using its current revision.", inputSchema: buildShape({ databaseId: ID, recordId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "expectedRevision", "operationId"]), handler: handler(bound, "archiveDatabaseRecord") },
     { name: "recover_database_record", description: "Recover one archived record using its current revision.", inputSchema: buildShape({ databaseId: ID, recordId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "expectedRevision", "operationId"]), handler: handler(bound, "recoverDatabaseRecord") },
     { name: "retry_database_sync", description: "Retry the shared append-only Knowledge summary projection after a canonical database mutation reported projectionPending.", inputSchema: buildShape({ databaseId: ID }, ["databaseId"]), handler: handler(bound, "retryDatabaseSync") },
+    { name: "import_database_records", description: "Import up to 100 source rows (256 KiB per batch) into a discovered database using immutable source identities and typed values. Use sourceNamespace/sourceKey references for same-batch or already-imported cross-database links; replay the exact operation and payload after uncertainty, and reread the current database revision before a stale retry.", inputSchema: buildShape({ databaseId: ID, expectedDatabaseRevision: REVISION, operationId: OPERATION, sourceNamespace: { type: "string", description: "Stable source namespace for this import mapping." }, rows: IMPORT_ROW_SCHEMA ? { schema: zod.array(IMPORT_ROW_SCHEMA), description: "At most 100 source rows and 256 KiB of serialized row JSON." } : { type: "array", description: "At most 100 source rows and 256 KiB of serialized row JSON.", items: IMPORT_ROW } }, ["databaseId", "expectedDatabaseRevision", "operationId", "sourceNamespace", "rows"]), handler: handler(bound, "importDatabaseRecords") },
+    { name: "read_database_import_progress", description: "Read bounded source-to-native record mappings by database id and source namespace. Use returned stable record ids for later corrections; this does not read arbitrary filesystem paths or caller-selected owners.", inputSchema: buildShape({ databaseId: ID, sourceNamespace: { type: "string" }, offset: { type: "number" }, limit: { type: "number", description: "Mapping page size from 1 to 100." } }, ["databaseId", "sourceNamespace"]), handler: handler(bound, "readDatabaseImportProgress") },
   ].map(function (tool) { tool.description = MATE_CONTRACT + " " + tool.description; return tool; });
 }
 
@@ -110,6 +127,36 @@ function mateTools(bound) {
       }, ["ref"]),
       handler: handler(bound, "readKnowledge"),
     },
+    {
+      name: "read_knowledge_document",
+      description: MATE_CONTRACT + " Read the complete current Markdown document by its relative path or stable document id, including its current revision.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID }, []),
+      handler: handler(bound, "readKnowledgeDocument"),
+    },
+    {
+      name: "create_knowledge_document",
+      description: MATE_CONTRACT + " Create a new Markdown document at a safe relative path. Use this for narrative or multiline content; it is synchronized into Knowledge search after the canonical save.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, content: { type: "string", description: "Complete Markdown document content." } }, ["name", "content"]),
+      handler: handler(bound, "createKnowledgeDocument"),
+    },
+    {
+      name: "update_knowledge_document",
+      description: MATE_CONTRACT + " Update an existing Markdown document by relative path or stable document id. The current revision is mandatory, and stale writes are rejected.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID, content: { type: "string", description: "Complete replacement Markdown document content." }, expectedRevision: DOCUMENT_REVISION }, ["content", "expectedRevision"]),
+      handler: handler(bound, "updateKnowledgeDocument"),
+    },
+    {
+      name: "list_knowledge_document_history",
+      description: MATE_CONTRACT + " List recoverable revisions for one Markdown document by relative path or stable document id.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID }, []),
+      handler: handler(bound, "listKnowledgeDocumentHistory"),
+    },
+    {
+      name: "restore_knowledge_document",
+      description: MATE_CONTRACT + " Restore a selected historical Markdown revision. The current revision is mandatory so a concurrent edit cannot be overwritten.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID, version: { type: "string", description: "Version returned by list_knowledge_document_history." }, expectedRevision: DOCUMENT_REVISION }, ["version", "expectedRevision"]),
+      handler: handler(bound, "restoreKnowledgeDocument"),
+    },
   ].concat(databaseTools(bound));
 }
 

package/lib/mate-knowledge-service.js

@@ -15,6 +15,8 @@ var builtinMates = require("./builtin-mates");
 var knowledgeImport = require("./knowledge-import");
 var knowledgeSearch = require("./knowledge-search");
 var mateSync = require("./mate-knowledge-sync");
+var textToolsModule = require("./mate-knowledge-text-tools");
+var mateBoundModule = require("./mate-knowledge-mate-bound");
 
 var MAX_PAGE = 50;
 var DEFAULT_PAGE = 20;
@@ -97,6 +99,7 @@ function attachMateKnowledgeService(ctx) {
   var listMates = context.listMates || function () { return []; };
   var baseDir = context.baseDir;
   var importerCache = new Map();
+  var textTools = textToolsModule.createMateKnowledgeTextTools({ baseDir: baseDir });
 
   function importerForScope(scopeId) {
     if (context.openImporter) return context.openImporter(scopeId);
@@ -379,6 +382,8 @@ function attachMateKnowledgeService(ctx) {
     if (source.session) {
       var manager = project.getSessionManager ? project.getSessionManager() : project.sm;
       if (!manager || !manager.sessions || manager.sessions.get(source.session.localId) !== source.session) return null;
+      if (source.projectOwnerId && source.session.ownerId && source.session.ownerId !== source.projectOwnerId) return null;
+      if (isMultiUser() && (!source.projectOwnerId || source.session.ownerId !== source.projectOwnerId)) return null;
     }
     if (typeof resolveMate !== "function") return null;
     var mate = resolveMate(source.projectOwnerId || null, source.mateId);
@@ -422,36 +427,10 @@ function attachMateKnowledgeService(ctx) {
   // An ordinary Mate's own scope, and nothing else. There is no argument on
   // any tool that could widen it.
   function createMateBound(revalidate, initial) {
-    function ownScope() {
-      return [revalidate().own];
-    }
-    function db(method, args) {
-      var current = revalidate(); if (!current.databaseService || typeof current.databaseService[method] !== "function") throw new Error("Knowledge databases are unavailable for this Mate.");
-      return current.databaseService[method](Object.assign({}, args || {}, { actor: current.actor }));
-    }
-    return {
-      isClay: false,
-      mateId: initial.own.mateId,
-      scopeId: initial.own.scopeId,
-      listKnowledge: function (args) { return listFor(ownScope(), args || {}, false); },
-      searchKnowledge: function (args) { return searchFor(ownScope(), args || {}, false); },
-      readKnowledge: function (args) { return readFor(ownScope(), args || {}, false); },
-      listDatabases: function (args) { return db("list", args); },
-      createDatabase: function (args) { return db("create", args); },
-      readDatabase: function (args) { return db("read", args); },
-      renameDatabase: function (args) { return db("rename", args); },
-      archiveDatabase: function (args) { return db("archive", args); },
-      recoverDatabase: function (args) { return db("recover", args); },
-      updateDatabaseSchema: function (args) { return db("updateSchema", args); },
-      saveTableView: function (args) { return db("saveView", args); },
-      queryDatabase: function (args) { return db("query", args); },
-      createDatabaseRecord: function (args) { return db("createRecord", args); },
-      readDatabaseRecord: function (args) { return db("readRecord", args); },
-      updateDatabaseRecord: function (args) { return db("updateRecord", args); },
-      archiveDatabaseRecord: function (args) { return db("archiveRecord", args); },
-      recoverDatabaseRecord: function (args) { return db("recoverRecord", args); },
-      retryDatabaseSync: function (args) { return db("retryProjection", args); },
-    };
+    return mateBoundModule.createMateBound({
+      revalidate: revalidate, initial: initial, textTools: textTools,
+      listFor: listFor, searchFor: searchFor, readFor: readFor,
+    });
   }
 
   // Every Mate belonging to the same user, resolved fresh on each call so a

package/lib/mate-knowledge-text-tools.js

@@ -0,0 +1,106 @@
+// Session-bound text Knowledge mutations for one authorized Mate.
+//
+// This module deliberately uses the existing portable file store and
+// write-through synchronizer. It never accepts a Mate, owner, or filesystem
+// root from a tool caller; the caller supplies only a relative document name
+// or the stable identity returned by the store.
+
+var crypto = require("crypto");
+var path = require("path");
+var knowledgeFiles = require("./knowledge-file-store");
+var mateSync = require("./mate-knowledge-sync");
+
+function metadataRoot(baseDir, mateDir) {
+  var key = crypto.createHash("sha256").update(path.resolve(mateDir)).digest("hex").slice(0, 24);
+  return path.join(baseDir || path.join(mateDir, ".clay"), "knowledge-documents", key);
+}
+
+function failedSync(summary) {
+  if (!summary) return { indexSyncPending: true, syncError: "Knowledge index synchronization returned no result." };
+  if (summary.failed === 0) return { indexSyncPending: false, syncError: null };
+  var error = summary.errors && summary.errors[0];
+  return { indexSyncPending: true, syncError: error && error.message || "Knowledge index synchronization failed." };
+}
+
+function createMateKnowledgeTextTools(options) {
+  var settings = options || {};
+  var stores = new Map();
+
+  function storeFor(mate) {
+    if (!mate || typeof mate.mateDir !== "string") throw new Error("Knowledge text tools require an authorized Mate.");
+    var directory = path.resolve(mate.mateDir);
+    if (!stores.has(directory)) stores.set(directory, knowledgeFiles.createKnowledgeFileStore(directory, { metaDir: metadataRoot(settings.baseDir, directory) }));
+    return stores.get(directory);
+  }
+
+  function find(store, input) {
+    var args = input || {};
+    var hasName = typeof args.name === "string" && args.name.length > 0;
+    var hasId = typeof args.documentId === "string" && args.documentId.length > 0;
+    if (!hasName && !hasId) throw new Error("A document name or stable document id is required.");
+    var item = null;
+    if (hasId) item = store.list().filter(function (entry) { return entry.id === args.documentId; })[0] || null;
+    if (hasId && !item) throw Object.assign(new Error("Knowledge document not found."), { code: "ENOENT" });
+    if (hasName) {
+      var byName = store.read(args.name);
+      if (item && item.id !== byName.id) throw new Error("The document name and id identify different documents.");
+      item = byName;
+    }
+    if (!item) throw Object.assign(new Error("Knowledge document not found."), { code: "ENOENT" });
+    if (hasId && !hasName) item = store.read(item.name);
+    if (item.itemType !== "text") throw Object.assign(new Error("Only Markdown Knowledge documents are writable through these tools."), { code: "READ_ONLY" });
+    return item;
+  }
+
+  function sync(mate, name, actor) {
+    try {
+      var summary = mateSync.syncMateSource({ mateDir: mate.mateDir, fileName: name, baseDir: settings.baseDir, actor: actor });
+      return failedSync(summary);
+    } catch (error) {
+      return { indexSyncPending: true, syncError: error.message || "Knowledge index synchronization failed." };
+    }
+  }
+
+  function read(mate, args) {
+    var item = find(storeFor(mate), args);
+    return { documentId: item.id, name: item.name, content: item.content, revision: item.revision };
+  }
+
+  function create(mate, args, actor) {
+    var input = args || {};
+    if (typeof input.name !== "string" || !input.name) throw new Error("A document name is required to create a Knowledge document.");
+    if (typeof input.content !== "string") throw new Error("Document content is required.");
+    var store = storeFor(mate);
+    var saved = store.save(input.name, input.content, null);
+    return Object.assign({ documentId: saved.id, name: saved.name, revision: saved.revision }, sync(mate, saved.name, actor));
+  }
+
+  function update(mate, args, actor) {
+    var input = args || {};
+    if (typeof input.expectedRevision !== "string" || !input.expectedRevision) throw Object.assign(new Error("A current document revision is required for updates."), { code: "STALE" });
+    if (typeof input.content !== "string") throw new Error("Document content is required.");
+    var store = storeFor(mate);
+    var current = find(store, input);
+    var saved = store.save(current.name, input.content, input.expectedRevision);
+    return Object.assign({ documentId: saved.id, name: saved.name, revision: saved.revision }, sync(mate, saved.name, actor));
+  }
+
+  function history(mate, args) {
+    var current = find(storeFor(mate), args);
+    return { documentId: current.id, name: current.name, versions: storeFor(mate).history(current.id) };
+  }
+
+  function restore(mate, args, actor) {
+    var input = args || {};
+    if (typeof input.expectedRevision !== "string" || !input.expectedRevision) throw Object.assign(new Error("A current document revision is required for restore."), { code: "STALE" });
+    if (typeof input.version !== "string" || !input.version) throw new Error("A history version is required.");
+    var store = storeFor(mate);
+    var current = find(store, input);
+    var restored = store.restore(current.id, input.version, current.name, input.expectedRevision);
+    return Object.assign({ documentId: restored.id, name: restored.name, revision: restored.revision }, sync(mate, restored.name, actor));
+  }
+
+  return { read: read, create: create, update: update, history: history, restore: restore };
+}
+
+module.exports = { createMateKnowledgeTextTools: createMateKnowledgeTextTools };

package/lib/project-connection.js

@@ -301,7 +301,7 @@ function attachConnection(ctx) {
       }
       sendTo(ws, { type: "history_meta", total: total, from: fromIndex });
       for (var i = fromIndex; i < total; i++) {
-        sendTo(ws, hydrateImageRefs(active.history[i]));
+        sendTo(ws, Object.assign({}, hydrateImageRefs(active.history[i]), { _historyIndex: i }));
       }
       var _lastUsage = null, _lastModelUsage = null, _lastCost = null, _lastStreamInputTokens = null;
       for (var _ri = total - 1; _ri >= 0; _ri--) {

package/lib/project-mate-interaction.js

@@ -3,6 +3,7 @@ var fs = require("fs");
 var path = require("path");
 var crypto = require("crypto");
 var mateSync = require("./mate-knowledge-sync");
+var dmDigestCursor = require("./dm-digest-cursor");
 
 // Mirror a Mate-owned journal into the Clay-wide Knowledge backend after the
 // legacy append has already succeeded. Reconciling the whole journal keeps the
@@ -294,6 +295,9 @@ function attachMateInteraction(ctx) {
         mirrorMateJournal(mateDir, "session-digests.jsonl", job);
       } catch (e) {
         console.error("[digest-worker] Write failed for " + job.mateId + ":", e.message);
+        if (job.onError) job.onError(e);
+        processDigestQueue();
+        return;
       }
 
       // Write user observations if present
@@ -422,63 +426,19 @@ function attachMateInteraction(ctx) {
   // Delta-based: only collects new turns since the last successful digest.
   // Concurrency debounce: turns that arrive while a digest is in-flight
   // are naturally batched into the next flush.
-  var _dmDigestPending = false;
-  function digestDmTurn(session, responsePreview) {
-    if (!isMate || _dmDigestPending) return;
+  var _dmDigestPending = new WeakSet();
+  function digestDmTurn(session) {
+    if (!isMate || _dmDigestPending.has(session)) return;
     var mateId = path.basename(cwd);
     var mateCtx = matesModule.buildMateCtx(projectOwnerId);
     if (!matesModule.isMate(mateCtx, mateId)) return;
 
-    // Track digest index per session so switching sessions doesn't misalign.
-    // On resumed sessions (after restart), recover index from the last
-    // digest_checkpoint entry in history so undigested turns aren't lost.
-    if (typeof session._dmLastDigestedIndex !== "number") {
-      session._dmLastDigestedIndex = 0;
-      for (var ci = session.history.length - 1; ci >= 0; ci--) {
-        if (session.history[ci].type === "digest_checkpoint") {
-          session._dmLastDigestedIndex = session.history[ci].digestedIndex;
-          break;
-        }
-      }
-    }
-
-    // Collect only new turns since the last successful digest
-    var conversationParts = [];
-    var totalLen = 0;
-    var CONV_CAP = 6000;
-    var startIndex = session._dmLastDigestedIndex;
-    for (var hi = startIndex; hi < session.history.length; hi++) {
-      if (totalLen >= CONV_CAP) break;
-      var entry = session.history[hi];
-      if (entry.type === "user_message" && entry.text) {
-        var uText = entry.text;
-        if (totalLen + uText.length > CONV_CAP) {
-          uText = uText.substring(0, Math.max(200, CONV_CAP - totalLen)) + "...";
-        }
-        conversationParts.push("User: " + uText);
-        totalLen += uText.length;
-      } else if (entry.type === "assistant_message" && entry.text) {
-        var aText = entry.text;
-        if (totalLen + aText.length > CONV_CAP) {
-          aText = aText.substring(0, Math.max(200, CONV_CAP - totalLen)) + "...";
-        }
-        conversationParts.push("Mate: " + aText);
-        totalLen += aText.length;
-      }
-    }
-    // If the latest response hasn't landed in history yet, append it
-    var lastResponseText = responsePreview || "";
-    if (lastResponseText && conversationParts.length > 0) {
-      var lastPart = conversationParts[conversationParts.length - 1];
-      if (lastPart.indexOf("Mate:") !== 0 || lastPart.indexOf(lastResponseText.substring(0, 50)) === -1) {
-        var rText = lastResponseText;
-        if (totalLen + rText.length > CONV_CAP) {
-          rText = rText.substring(0, Math.max(200, CONV_CAP - totalLen)) + "...";
-        }
-        conversationParts.push("Mate: " + rText);
-      }
-    }
-    if (conversationParts.length === 0) return;
+    // Recover the exact next unread position. Legacy index-only checkpoints
+    // remain readable and are treated as fully consumed entries.
+    var digestState = dmDigestCursor.readState(session.history);
+    var startCursor = digestState.cursor;
+    var chunk = dmDigestCursor.collectChunk(session.history, startCursor);
+    if (!chunk.conversationContent) return;
 
     var mateDir = matesModule.getMateDir(mateCtx, mateId);
     var knowledgeDir = path.join(mateDir, "knowledge");
@@ -500,8 +460,8 @@ function attachMateInteraction(ctx) {
       }
     } catch (e) {}
 
-    _dmDigestPending = true;
-    var snapshotIndex = session.history.length;
+    _dmDigestPending.add(session);
+    var checkpointCursor = chunk.cursor;
 
     enqueueDigest({
       mateCtx: mateCtx,
@@ -509,17 +469,27 @@ function attachMateInteraction(ctx) {
       mateId: mateId,
       type: "dm",
       priorSummary: priorSummary || "",
-      conversationContent: conversationParts.join("\n"),
+      conversationContent: chunk.conversationContent,
       onDone: function () {
-        session._dmLastDigestedIndex = snapshotIndex;
-        // Persist checkpoint so resumed sessions know where to continue
-        var checkpoint = { type: "digest_checkpoint", digestedIndex: snapshotIndex };
+        // Journal and checkpoint are separate appends: if this append fails,
+        // retry may duplicate the saved digest, but must never skip its input.
+        var checkpoint = { type: "digest_checkpoint", cursor: checkpointCursor };
+        var saved = false;
+        try { saved = sm.appendToSessionFile(session, checkpoint) !== false; } catch (e) {
+          console.error("[dm-digest] Checkpoint append failed:", e.message);
+        }
+        if (!saved) {
+          _dmDigestPending.delete(session);
+          return;
+        }
         session.history.push(checkpoint);
-        sm.appendToSessionFile(session, checkpoint);
-        _dmDigestPending = false;
+        _dmDigestPending.delete(session);
+        if (dmDigestCursor.hasPending(session.history, checkpointCursor)) {
+          setImmediate(function () { digestDmTurn(session, ""); });
+        }
       },
       onError: function () {
-        _dmDigestPending = false;
+        _dmDigestPending.delete(session);
       },
     });
   }

package/lib/project-sessions.js

@@ -588,7 +588,9 @@ function attachSessions(ctx) {
       var targetFrom = typeof msg.target === "number" ? msg.target : before - sm.HISTORY_PAGE_SIZE;
       var from = sm.findTurnBoundary(session.history, Math.max(0, targetFrom));
       var to = before;
-      var items = session.history.slice(from, to).map(hydrateImageRefs);
+      var items = session.history.slice(from, to).map(function (item, index) {
+        return Object.assign({}, hydrateImageRefs(item), { _historyIndex: from + index });
+      });
       sendTo(ws, {
         type: "history_prepend",
         items: items,

package/lib/public/app.js

@@ -315,6 +315,8 @@ import { initDebate, handleDebatePreparing, handleDebateStarted, handleDebateRes
     historyTotal: 0,
     replayingHistory: false,
     historyReplayBatch: null,
+    pendingSessionEntryNavigation: null,
+    sessionNavigationRequestId: null,
     projectName: projectName,
     cwd: "",
     currentSlug: currentSlug,

package/lib/public/css/command-palette.css

@@ -550,41 +550,20 @@ body.mate-dm-active .search-clay-transcript .search-clay-message-user .bubble,
 .clayos-issue-link { --record-color: var(--link, var(--accent)); }
 .clayos-log-link { --record-color: var(--accent); }
 
-.clayos-session-link {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  min-height: 26px;
-  margin: 2px 1px;
-  padding: 3px 8px 3px 6px;
-  border: 1px solid color-mix(in srgb, var(--accent) 28%, var(--border));
-  border-radius: 7px;
-  background: color-mix(in srgb, var(--accent) 7%, var(--bg-alt));
-  color: var(--text);
-  font: inherit;
-  font-size: 11px;
-  line-height: 1;
-  vertical-align: middle;
-  cursor: pointer;
+.clayos-session-link { --record-color: var(--accent); }
+
+#messages .session-entry-target {
+  outline: 2px solid color-mix(in srgb, var(--accent) 72%, transparent);
+  outline-offset: 3px;
+  border-radius: 8px;
+  background: color-mix(in srgb, var(--accent) 7%, transparent);
+  animation: sessionEntryTargetFade 1800ms ease-out forwards;
 }
-.clayos-session-link::before {
-  content: "\2197";
-  display: grid;
-  place-items: center;
-  width: 17px;
-  height: 17px;
-  border-radius: 5px;
-  background: color-mix(in srgb, var(--accent) 14%, transparent);
-  color: var(--accent);
-  font-size: 12px;
+
+@keyframes sessionEntryTargetFade {
+  0%, 72% { background: color-mix(in srgb, var(--accent) 10%, transparent); }
+  100% { background: transparent; }
 }
-.clayos-session-link > span { font-weight: 620; }
-.clayos-session-link > small { color: var(--text-muted); font-size: 10px; }
-.clayos-session-link:hover { border-color: color-mix(in srgb, var(--accent) 52%, var(--border)); background: color-mix(in srgb, var(--accent) 11%, var(--bg-alt)); }
-.clayos-session-link:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
-.clayos-session-link.is-loading { opacity: 0.62; cursor: progress; }
-.clayos-session-link.is-loading::before { animation: searchClaySpin 1.2s linear infinite; }
-.clayos-session-link.is-error { border-color: color-mix(in srgb, var(--warning) 48%, var(--border)); }
 
 .search-clay-pending {
   align-self: flex-start;

package/lib/public/modules/app-header.js

@@ -350,6 +350,7 @@ export function prependOlderHistory(items, meta) {
 
   // Save current rendering state
   var savedMsgEl = store.get('currentMsgEl');
+  var savedReplayingHistory = store.get('replayingHistory');
   var savedActivity = getActivityEl();
   var savedFullText = store.get('currentFullText');
   var savedTurnCounter = getTurnCounter();
@@ -359,7 +360,7 @@ export function prependOlderHistory(items, meta) {
   var savedUsage = JSON.parse(JSON.stringify(getSessionUsage()));
 
   // Reset to initial values for clean rendering
-  store.set({ currentMsgEl: null, currentFullText: "" });
+  store.set({ currentMsgEl: null, currentFullText: "", replayingHistory: true });
   setActivityEl(null);
   setTurnCounter(0);
   resetToolState();
@@ -387,7 +388,7 @@ export function prependOlderHistory(items, meta) {
   setPrependAnchor(null);
 
   // Restore saved state
-  store.set({ currentMsgEl: savedMsgEl, currentFullText: savedFullText });
+  store.set({ currentMsgEl: savedMsgEl, currentFullText: savedFullText, replayingHistory: savedReplayingHistory });
   setActivityEl(savedActivity);
   setTurnCounter(savedTurnCounter);
   restoreToolState(savedToolsState);