@cerefox/memory 0.10.4 → 0.11.1

package/dist/server-assets/supabase/functions/cerefox-ingest/index.ts

@@ -17,7 +17,9 @@ import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/inde
  *   content      string   required  Markdown content
  *   project_name string   optional  Project to assign to (looked up by name, created if absent)
  *   source       string   optional  Origin label (default: "agent")
- *   metadata     object   optional  Arbitrary JSONB metadata
+ *   metadata     object   optional  Arbitrary JSONB metadata. Omitted on an
+ *                                   update → existing metadata is KEPT
+ *                                   (v0.11.1); pass {} explicitly to clear.
  *
  * Response: { document_id, title, chunk_count, project_id? }
  */
@@ -40,6 +42,42 @@ interface IngestRequest {
   update_if_exists?: boolean;
   author?: string;
   author_type?: string; // 'user' | 'agent'
+  // Optimistic concurrency (iter-32): REQUIRED on content updates — the
+  // content_hash of the version this edit was based on. Conflict → HTTP 409.
+  expected_content_hash?: string;
+  // Explicitly skip the concurrency check (external source of truth).
+  last_write_wins?: boolean;
+}
+
+// Map the RPC's CEREFOX_CONFLICT / CEREFOX_TOKEN_REQUIRED errors to HTTP
+// responses (409 conflict / 400 missing token). Returns null for other errors.
+function concurrencyErrorResponse(
+  message: string,
+  headers: Record<string, string>,
+): Response | null {
+  if (message.includes("CEREFOX_CONFLICT")) {
+    return new Response(
+      JSON.stringify({
+        error: "conflict",
+        message:
+          "Document changed since it was read. Re-read it (getDocument), merge your changes, and retry with the new expected_content_hash.",
+        detail: message,
+      }),
+      { status: 409, headers },
+    );
+  }
+  if (message.includes("CEREFOX_TOKEN_REQUIRED")) {
+    return new Response(
+      JSON.stringify({
+        error: "expected_content_hash required",
+        message:
+          "Content updates require expected_content_hash (the content_hash returned by getDocument / searchKnowledgeBase / metadataSearch) or last_write_wins=true.",
+        detail: message,
+      }),
+      { status: 400, headers },
+    );
+  }
+  return null;
 }
 
 interface Chunk {
@@ -428,7 +466,10 @@ Deno.serve(async (req: Request) => {
     });
   }
 
-  const { title, content, document_id = null, project_name, source = "agent", metadata = {}, update_if_exists = false, author = "agent", author_type = "agent" } = body;
+  // metadata: null = "not provided" — the RPC keeps existing metadata on
+  // update and uses {} on create (v0.11.1; a `= {}` default here used to wipe
+  // a document's tags on every content update that didn't re-pass them).
+  const { title, content, document_id = null, project_name, source = "agent", metadata = null, update_if_exists = false, author = "agent", author_type = "agent", expected_content_hash = null, last_write_wins = false } = body;
 
   // Validate + normalize project_names if provided (full-set destructive form)
   let project_names: string[] | null = null;
@@ -525,6 +566,16 @@ Deno.serve(async (req: Request) => {
       );
     }
 
+    // Optimistic-concurrency fast-fail (iter-32): stale token fails BEFORE
+    // the embedding spend. Advisory only — the authoritative race-free check
+    // is inside the RPC (SELECT … FOR UPDATE).
+    if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
+      return concurrencyErrorResponse(
+        `CEREFOX_CONFLICT: document ${existingDoc.id} changed since it was read (expected hash ${expected_content_hash}, current hash ${existingDoc.content_hash}).`,
+        headers,
+      )!;
+    }
+
     // Content changed -- re-chunk, re-embed, ingest via RPC
     const chunks = chunkMarkdown(content);
     if (chunks.length === 0) {
@@ -562,9 +613,13 @@ Deno.serve(async (req: Request) => {
       p_author: author,
       p_author_type: author_type,
       p_source_label: source,
+      p_expected_content_hash: expected_content_hash,
+      p_last_write_wins: last_write_wins,
     });
 
     if (ingestErr) {
+      const mapped = concurrencyErrorResponse(ingestErr.message ?? "", headers);
+      if (mapped) return mapped;
       return new Response(JSON.stringify({ error: `Ingest RPC failed: ${ingestErr.message}` }), { status: 500, headers });
     }
 
@@ -593,6 +648,7 @@ Deno.serve(async (req: Request) => {
         chunk_count: chunks.length,
         total_chars: totalChars,
         updated: true,
+        content_hash: contentHash,
         ...(note && { note }),
       }),
       { headers },
@@ -625,6 +681,14 @@ Deno.serve(async (req: Request) => {
         );
       }
 
+      // Optimistic-concurrency fast-fail (iter-32) — see ID-based path.
+      if (!last_write_wins && expected_content_hash && expected_content_hash !== existingDoc.content_hash) {
+        return concurrencyErrorResponse(
+          `CEREFOX_CONFLICT: document ${existingDoc.id} changed since it was read (expected hash ${expected_content_hash}, current hash ${existingDoc.content_hash}).`,
+          headers,
+        )!;
+      }
+
       // Content changed — re-chunk, re-embed, ingest via RPC
       const chunks = chunkMarkdown(content);
       if (chunks.length === 0) {
@@ -667,9 +731,13 @@ Deno.serve(async (req: Request) => {
         p_author: author,
         p_author_type: author_type,
         p_source_label: source,
+        p_expected_content_hash: expected_content_hash,
+        p_last_write_wins: last_write_wins,
       });
 
       if (ingestErr) {
+        const mapped = concurrencyErrorResponse(ingestErr.message ?? "", headers);
+        if (mapped) return mapped;
         return new Response(
           JSON.stringify({ error: `Ingest RPC failed: ${ingestErr.message}` }),
           { status: 500, headers },
@@ -701,6 +769,7 @@ Deno.serve(async (req: Request) => {
           chunk_count: chunks.length,
           total_chars: totalChars,
           updated: true,
+          content_hash: contentHash,
         }),
         { headers },
       );

package/docs/guides/agent-coordination.md

@@ -33,6 +33,19 @@ The coordination model is **asynchronous and knowledge-based**:
 
 This is not real-time orchestration. It is persistent, searchable shared memory.
 
+### Concurrent writers are conflict-guarded (v0.11+)
+
+Shared memory means two agents can hold the same document at once. Cerefox
+protects content updates with **optimistic concurrency control**: every read
+surface returns the document's `content_hash`, and a content update must pass
+it back as `expected_content_hash`. If the document changed in between, the
+write fails with a **conflict** instead of silently overwriting the other
+writer's work — the losing agent re-reads, merges, and retries with the fresh
+hash. (Versioning remains the recovery net; the conflict guard is the
+prevention layer.) An explicit `last_write_wins: true` exists for re-sync flows
+where an external source of truth makes conflicts meaningless — agents should
+never use it to silence a conflict. See `AGENT_GUIDE.md → Concurrent writers`.
+
 ---
 
 ## Coordination Patterns
@@ -53,7 +66,7 @@ A living document where agents record decisions, experiment outcomes, and lesson
 
 **Example**: A coding agent working on a project records "Chose PostgreSQL RPC approach over application-level logic because..." in a decision log document. Next week, a different agent working on a related feature searches Cerefox, finds the decision log, and understands the rationale without re-deriving it.
 
-**How it works**: Create a document with a structured format (date, context, decision, outcome). Use a consistent title or project tag so agents can find it. To add entries over time, re-ingest with `update_if_exists: true` (or `document_id`) — this replaces the document in place, so build the new full content by appending to the prior content you fetched.
+**How it works**: Create a document with a structured format (date, context, decision, outcome). Use a consistent title or project tag so agents can find it. To add entries over time, re-ingest with `update_if_exists: true` (or `document_id`) — this replaces the document in place, so build the new full content by appending to the prior content you fetched, and pass the `content_hash` you fetched as `expected_content_hash` (two agents appending entries concurrently is exactly the conflict the guard catches).
 
 **Best for**: Project-level institutional memory, avoiding repeated decisions, onboarding new agent sessions.
 

package/docs/guides/cli.md

@@ -43,9 +43,11 @@ cerefox document ingest --paste --title "<title>" [OPTIONS]   # stdin
 | `--title` | `-t` | str | filename stem | Document title. Required with `--paste`. |
 | `--project-name` | `--project`, `-p` | str | _none_ | Project name to assign the document to (created if missing). |
 | `--paste` | — | flag | off | Read markdown from stdin. Requires `--title`. |
-| `--metadata` | `-m` | JSON | `{}` | Extra metadata as a JSON object, e.g. `'{"tags":["work"]}'`. |
+| `--metadata` | `-m` | JSON | _not provided_ | Extra metadata as a JSON object, e.g. `'{"tags":["work"]}'`. **On update, omitting this keeps the document's existing metadata** (v0.11.1); pass `'{}'` to deliberately clear all metadata. |
 | `--update-if-exists` | `-u` | flag | off | Title/source-path-based fallback update. Mutually exclusive with `--document-id`. |
 | `--document-id` | `-i` | UUID | _none_ | Deterministic ID-based update. Errors if the document doesn't exist. |
+| `--expected-content-hash` | — | sha256 | _none_ | **Required on content updates** (v0.11 optimistic concurrency): the `content_hash` of the version this edit is based on, shown by `cerefox document get` / `cerefox search`. Stale → conflict error (re-read, merge, retry). |
+| `--last-write-wins` | — | flag | off | Skip the concurrency check and overwrite regardless of concurrent changes. For re-sync flows where an external source of truth makes conflicts meaningless. Recorded in the audit log. |
 | `--source` | — | str | `paste` / `file` | Source label recorded on the document. |
 | `--author` | — | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Audit-log author identity. |
 | `--author-type` | — | `user`\|`agent` | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type. Agent writes auto-routed to `pending_review`. |
@@ -63,12 +65,19 @@ cerefox document ingest notes.md \
   --author "claude-code" --author-type "agent" \
   --project-name "research" --metadata '{"type":"design-doc"}'
 
-# Deterministic update (preferred — agents should search → grab ID → ingest)
+# Deterministic update (preferred — agents should search → grab ID + hash → ingest)
 cerefox document ingest --paste --title "Same Title" \
   --document-id "abc12345-..." \
+  --expected-content-hash "<hash from `document get`>" \
   --author "claude-code" --author-type "agent"
 ```
 
+> **Concurrency (v0.11+)**: content updates require `--expected-content-hash`
+> (or an explicit `--last-write-wins`). On a conflict, re-run
+> `cerefox document get <id>`, merge your changes into the latest content, and
+> retry with the new hash. `document ingest-dir` and `guides ingest` bypass the
+> check internally (the filesystem / npm package is their source of truth).
+
 **Output**: human-readable summary line(s) — "Ingested" or "Updated" with the document ID, chunk count, character count.
 
 **Exit codes**: `0` success, `1` on validation error (missing `--title`, invalid JSON, document-not-found, mutually-exclusive flags, etc.).
@@ -183,7 +192,7 @@ cerefox document get abc12345-... --version-id <version-uuid>     # archived
 cerefox document get abc12345-... | bat -l md                  # pipe to viewer
 ```
 
-**Output**: title + metadata line, blank line, then raw markdown.
+**Output**: title + metadata line + `content_hash` line (the optimistic-concurrency token — pass back via `document ingest --expected-content-hash` when updating), blank line, then raw markdown.
 
 **MCP equivalent**: [`cerefox_get_document`](../../AGENT_GUIDE.md).
 
@@ -401,8 +410,8 @@ cerefox metadata search --metadata-filter '<json>' [OPTIONS]
 
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `--metadata-filter <json>` (`-f`) | JSON | **required** | Metadata filter, e.g. `'{"type":"decision-log"}'`. |
-| `--project-name <name>` (`-p`) | str | _none_ | Filter by project name. |
+| `--metadata-filter <json>` (`-f`) | JSON | _none_ | Metadata filter, e.g. `'{"type":"decision-log"}'`. Optional since v0.11.1 — at least one of filter / `--project-name` / `--updated-since` / `--created-since` is required (parity with the MCP tool). |
+| `--project-name <name>` (`-p`) | str | _none_ | Filter by project name. Sufficient on its own to list that project's documents. |
 | `--updated-since TEXT` | ISO-8601 | _none_ | Documents updated after this timestamp. |
 | `--created-since TEXT` | ISO-8601 | _none_ | Documents created after this timestamp. |
 | `--limit INTEGER` | int | `10` | Max results. |
@@ -633,7 +642,7 @@ Every MCP parameter has an exact-name CLI flag (kebab-cased). Short forms exist
 | MCP tool | CLI command |
 |---|---|
 | `cerefox_search(query, match_count, project_name, metadata_filter, requestor)` | `cerefox search "<q>" --match-count N --project-name <name> --metadata-filter '<json>' --requestor <name>` |
-| `cerefox_ingest(title, content, project_name, metadata, update_if_exists, document_id, source, author, author_type)` (file) | `cerefox document ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --source <s> --author <a> --author-type <t>` |
+| `cerefox_ingest(title, content, project_name, metadata, update_if_exists, document_id, expected_content_hash, last_write_wins, source, author, author_type)` (file) | `cerefox document ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --expected-content-hash <hash>\|--last-write-wins --source <s> --author <a> --author-type <t>` |
 | `cerefox_ingest(...)` (paste) | `printf '...' \| cerefox document ingest --paste --title "<t>"` (same flags) |
 | `cerefox_get_document(document_id, version_id, requestor)` | `cerefox document get <id> --version-id <vid> --requestor <name>` |
 | `cerefox_list_versions(document_id, requestor)` | `cerefox document version list <id> --requestor <name>` |
@@ -709,12 +718,18 @@ cerefox document ingest-dir ./papers --extensions .md \
 # Step 1: find it
 cerefox search "the OAuth design doc" --match-count 1
 
-# Step 2: copy the id from `Doc: ... (id: <uuid>)` line
-# Step 3: update in place
+# Step 2: read it — note the id AND the `content_hash:` line (the concurrency token)
+cerefox document get "<uuid>"
+
+# Step 3: update in place, proving freshness with the hash from step 2
 printf '%s' "$NEW_CONTENT" | cerefox document ingest --paste \
   --title "OAuth 2.1 Design Document" \
   --document-id "<uuid>" \
+  --expected-content-hash "<hash>" \
   --author "claude-code" --author-type "agent"
+
+# On a conflict error: repeat from step 2 (fresh content + fresh hash),
+# merge your changes into the latest content, then retry.
 ```
 
 ### Unattended sync job

package/docs/guides/connect-agents.md

@@ -568,6 +568,11 @@ You have access to a personal knowledge base via the searchKnowledgeBase action.
 When the user asks a question, always search the knowledge base first using a
 relevant query. Present results by document title, citing the source for every claim.
 Use ingestNote to save any new information the user asks you to remember.
+When UPDATING an existing document, first call getDocument and note its
+content_hash, then pass it as expected_content_hash on ingestNote. If you get a
+409 conflict, the document changed underneath you: call getDocument again, merge
+your changes into the latest content, and retry with the new hash — never
+overwrite blindly.
 ```
 
 ### Path B verification
@@ -604,7 +609,7 @@ In the action editor, paste this schema (replace `<your-project-ref>`):
 openapi: 3.1.0
 info:
   title: Cerefox Knowledge Base
-  version: 1.9.0
+  version: 2.1.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -723,6 +728,10 @@ paths:
                   default: agent
                 metadata:
                   type: object
+                  description: >
+                    Arbitrary JSON metadata. On an UPDATE, omitting this keeps
+                    the document's existing metadata (v2.1.0); pass {} to
+                    deliberately clear all tags.
                 update_if_exists:
                   type: boolean
                   default: false
@@ -731,6 +740,23 @@ paths:
                     instead of creating a new one. The previous content is archived
                     as a version. If content is unchanged, the document is skipped
                     (no re-indexing). Ignored when document_id is provided.
+                expected_content_hash:
+                  type: string
+                  description: >
+                    REQUIRED on content updates (optimistic concurrency, v2.0.0):
+                    the content_hash of the version this edit was based on, as
+                    returned by getDocument / searchKnowledgeBase / metadataSearch.
+                    If the document changed since it was read, the update fails
+                    with HTTP 409 — re-read the document, merge your changes,
+                    retry with the new hash. Not needed when creating.
+                last_write_wins:
+                  type: boolean
+                  default: false
+                  description: >
+                    Explicitly skip the concurrency check and overwrite regardless
+                    of concurrent changes. Use ONLY when an external source of
+                    truth makes conflicts meaningless. Recorded in the audit log.
+                    Never use it to silence a 409 conflict.
                 author:
                   type: string
                   description: >
@@ -753,8 +779,19 @@ paths:
               project_id?, project_name?,   # set when a project was assigned on create
               skipped?,                      # true when identical content was deduplicated
               updated?,                      # true when an existing doc was updated
+              content_hash?,                 # the NEW hash after an update (the next edit's token)
               message?,                      # human note on dedup/skip/update
               note? }                        # note when a flag (e.g. update_if_exists) was overridden
+        '400':
+          description: >
+            Missing expected_content_hash on a content update (and
+            last_write_wins not set). Read the document first, then retry
+            with its content_hash.
+        '409':
+          description: >
+            Conflict — the document changed since it was read. Call getDocument
+            for the latest content + content_hash, merge your changes, and
+            retry with the new hash. Do not overwrite blindly.
   /cerefox-metadata:
     post:
       operationId: listMetadataKeys
@@ -802,7 +839,9 @@ paths:
           description: >
             Document content and metadata:
             { document_id, doc_title, full_content, chunk_count, total_chars,
-              is_archived, version_id }
+              is_archived, version_id, content_hash }.
+            content_hash is the document's CURRENT hash — pass it back as
+            expected_content_hash when updating via ingestNote.
         '404':
           description: Document not found
   /cerefox-list-versions:
@@ -952,7 +991,9 @@ paths:
             Array of matching documents:
             [{ document_id, title, doc_metadata, review_status, source, created_at,
                updated_at, total_chars, chunk_count, project_ids, project_names,
-               version_count, content }]
+               version_count, content_hash, content }].
+            content_hash is the concurrency token — pass it back as
+            expected_content_hash when updating via ingestNote.
 ```
 
 **Step 3 — Configure authentication**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "0.10.4",
+  "version": "0.11.1",
   "description": "Cerefox — user-owned shared memory for AI agents. The local TypeScript runtime: stdio MCP server in v0.4; CLI binary added in v0.5; in-process web server in v0.6; ingestion pipeline in v0.7.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",