@cerefox/memory 1.13.1 → 1.14.0

package/docs/guides/cli.md

@@ -149,14 +149,14 @@ cerefox search [OPTIONS] QUERY
 | `--metadata-filter <json>` (`-f`) | JSON | _none_ | JSONB metadata containment filter, e.g. `'{"type":"decision"}'`. |
 | `--max-bytes <n>` | int | `200000` | Response size budget in bytes. |
 | `--only-metadata` | flag | off | List matching docs (id, score, chunks, chars) without content — a compact listing. |
-| `--requestor <name>` (`-r`) | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
+| `--author <name>` (`-a`) | str | `CEREFOX_REQUESTOR_NAME`, then `CEREFOX_AUTHOR_NAME`, else `unknown` | Your name (agent or user), recorded in the usage log. `--requestor` (`-r`) still works as a hidden alias (v1.13.2). |
 | `--json` | flag | off | Machine-readable JSON output. |
 
 **Examples**:
 ```bash
 cerefox search "OAuth design"
 cerefox search "decisions" --metadata-filter '{"type":"decision-log"}' --match-count 5
-cerefox search "what we tried" --mode hybrid --requestor "claude-code"
+cerefox search "what we tried" --mode hybrid --author "claude-code"
 cerefox search "design docs" --only-metadata
 ```
 
@@ -182,7 +182,7 @@ cerefox document get [OPTIONS] DOCUMENT_ID
 | Flag | Type | Default | Description |
 |---|---|---|---|
 | `--version-id <uuid>` | UUID | _none_ (current) | Archived version UUID — get from `cerefox document version list`. |
-| `--requestor <name>` (`-r`) | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
+| `--author <name>` (`-a`) | str | `CEREFOX_REQUESTOR_NAME`, then `CEREFOX_AUTHOR_NAME`, else `unknown` | Your name (agent or user), recorded in the usage log. `--requestor` (`-r`) still works as a hidden alias (v1.13.2). |
 | `--json` | flag | off | Machine-readable JSON output. |
 
 **Examples**:
@@ -394,7 +394,7 @@ cerefox document version list [OPTIONS] DOCUMENT_ID
 
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `--requestor TEXT` | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
+| `--author TEXT` (`-a`) | str | `CEREFOX_REQUESTOR_NAME`, then `CEREFOX_AUTHOR_NAME`, else `unknown` | Your name (agent or user), recorded in the usage log. `--requestor` (`-r`) still works as a hidden alias (v1.13.2). |
 
 **Output**: table with version number, created timestamp, source, chunk/char counts, and version UUID. Pass the UUID to `cerefox document get --version-id <uuid>` to retrieve the archived content.
 
@@ -429,7 +429,7 @@ cerefox project list [OPTIONS]
 
 | Flag | Type | Default | Description |
 |---|---|---|---|
-| `--requestor TEXT` | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
+| `--author TEXT` (`-a`) | str | `CEREFOX_REQUESTOR_NAME`, then `CEREFOX_AUTHOR_NAME`, else `unknown` | Your name (agent or user), recorded in the usage log. `--requestor` (`-r`) still works as a hidden alias (v1.13.2). |
 
 **MCP equivalent**: [`cerefox_list_projects`](../../AGENT_GUIDE.md).
 
@@ -498,7 +498,7 @@ cerefox metadata search --metadata-filter '<json>' [OPTIONS]
 | `--created-since TEXT` | ISO-8601 | _none_ | Documents created after this timestamp. |
 | `--limit INTEGER` | int | `10` | Max results. |
 | `--include-content` | flag | off | Include full document content (slower; subject to byte budget). |
-| `--requestor TEXT` | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
+| `--author TEXT` (`-a`) | str | `CEREFOX_REQUESTOR_NAME`, then `CEREFOX_AUTHOR_NAME`, else `unknown` | Your name (agent or user), recorded in the usage log. `--requestor` (`-r`) still works as a hidden alias (v1.13.2). |
 
 **Examples**:
 ```bash
@@ -526,13 +526,13 @@ cerefox audit list [OPTIONS]
 | Flag | Type | Default | Description |
 |---|---|---|---|
 | `--document-id TEXT` | UUID | _none_ | Filter to a single document. |
-| `--author TEXT` | str | _none_ | Filter by author name (exact match). |
+| `--by-author TEXT` | str | _none_ | Filter: only entries written by this author name (exact match). Until v1.13.2 this filter was `--author`; `--author` is now the caller identity here, as on every other command. |
 | `--operation TEXT` | choice | _none_ | Filter by operation type: `create`, `update-content`, `update-metadata`, `insert`, `replace-section`, `delete-section`, `rename-section`, `delete`, `restore`, `status-change`, `archive`, `unarchive`, `config-change`, `project-create`, `project-edit`, `project-delete`. |
 | `--since TEXT` | ISO-8601 | _none_ | Lower bound on `created_at`. |
 | `--until TEXT` | ISO-8601 | _none_ | Upper bound on `created_at`. |
 | `--limit INTEGER` | int | `50` | Max rows. |
 | `--json` | flag | off | Emit one JSON object per line (for piping to `jq` / scripts). |
-| `--requestor TEXT` | str | `CEREFOX_REQUESTOR_NAME` or `user` | Identity recorded in the usage log. |
+| `--author TEXT` (`-a`) | str | `CEREFOX_REQUESTOR_NAME`, then `CEREFOX_AUTHOR_NAME`, else `unknown` | Your name (agent or user), recorded in the usage log. `--requestor` (`-r`) still works as a hidden alias (v1.13.2). |
 
 **Examples**:
 ```bash
@@ -540,7 +540,7 @@ cerefox audit list [OPTIONS]
 cerefox audit list --since 2026-05-11
 
 # All edits by a specific agent
-cerefox audit list --author "claude-code" --operation update-content
+cerefox audit list --by-author "claude-code" --operation update-content
 
 # JSON output, piped to jq
 cerefox audit list --json --limit 1000 | jq 'select(.author_type == "agent")'
@@ -791,7 +791,7 @@ The CLI reads its own runtime config from environment (or `.env`). See [`configu
 |---|---|---|
 | `CEREFOX_AUTHOR_NAME` | `unknown` | Default for `--author` on `ingest` / `ingest-dir`. |
 | `CEREFOX_AUTHOR_TYPE` | `user` | Default for `--author-type`. |
-| `CEREFOX_REQUESTOR_NAME` | `user` | Default for `--requestor` on read commands. |
+| `CEREFOX_REQUESTOR_NAME` | `unknown` | Default for `--author` on read commands (falls back to `CEREFOX_AUTHOR_NAME`, then `unknown`). |
 
 Precedence: **CLI flag > env var > built-in default**.
 
@@ -811,18 +811,18 @@ 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, author)` | `cerefox search "<q>" --match-count N --project-name <name> --metadata-filter '<json>' --requestor <name>` |
+| `cerefox_search(query, match_count, project_name, metadata_filter, author)` | `cerefox search "<q>" --match-count N --project-name <name> --metadata-filter '<json>' --author <name>` |
 | `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, outline, author)` | `cerefox document get <id> --version-id <vid> --outline --requestor <name>` |
-| `cerefox_insert(document_id, text, position, anchor_heading, section_part, expected_content_hash, author)` | `cerefox document insert <id> -t <text\|-\|@file> -p <position> -a <anchor> --section-part <part> --expected-hash <hash> --requestor <name>` |
-| `cerefox_edit(document_id, operations, expected_content_hash, author)` | `cerefox document edit-parts <id> -o <json\|-\|@file> --expected-hash <hash> --requestor <name>` |
-| `cerefox_list_versions(document_id, author)` | `cerefox document version list <id> --requestor <name>` |
-| `cerefox_list_projects(author)` | `cerefox project list --requestor <name>` |
+| `cerefox_get_document(document_id, version_id, outline, author)` | `cerefox document get <id> --version-id <vid> --outline --author <name>` |
+| `cerefox_insert(document_id, text, position, anchor_heading, section_part, expected_content_hash, author)` | `cerefox document insert <id> -t <text\|-\|@file> -p <position> -a <anchor> --section-part <part> --expected-hash <hash> --author <name>` |
+| `cerefox_edit(document_id, operations, expected_content_hash, author)` | `cerefox document edit-parts <id> -o <json\|-\|@file> --expected-hash <hash> --author <name>` |
+| `cerefox_list_versions(document_id, author)` | `cerefox document version list <id> --author <name>` |
+| `cerefox_list_projects(author)` | `cerefox project list --author <name>` |
 | `cerefox_set_document_projects(document_id, project_names, author)` | `cerefox document set-projects <id> <name...> --author <a> --author-type <t>` (or `--clear` to remove all) |
 | `cerefox_list_metadata_keys()` | `cerefox metadata keys` |
-| `cerefox_metadata_search(metadata_filter, project_name, updated_since, created_since, limit, include_content, author)` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --updated-since <iso> --created-since <iso> --limit N --include-content --requestor <name>` |
-| `cerefox_get_audit_log(document_id, by_author, operation, since, until, limit, author)` | `cerefox audit list --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --requestor <name>` |
+| `cerefox_metadata_search(metadata_filter, project_name, updated_since, created_since, limit, include_content, author)` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --updated-since <iso> --created-since <iso> --limit N --include-content --author <name>` |
+| `cerefox_get_audit_log(document_id, by_author, operation, since, until, limit, author)` | `cerefox audit list --document-id <id> --by-author <a> --operation <op> --since <iso> --until <iso> --limit N --author <name>` |
 | `cerefox_set_document_metadata(document_id, metadata, replace, author)` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json '<json>'`, `--replace`) |
 | `cerefox_delete_document(document_id, expected_content_hash, reason, author)` | `cerefox document delete <id> --reason <text> --author <a> --author-type <t> --yes` (confirms interactively instead of requiring the hash) |
 | `cerefox_restore_document(document_id, reason, author)` | `cerefox document restore <id> --reason <text> --author <a> --author-type <t>` |

package/docs/guides/configuration.md

@@ -488,8 +488,12 @@ multi-agent setups.
 Since v1.13.1 every MCP tool takes the caller's identity as **`author`**, reads and
 writes alike; `requestor` (the pre-1.13.1 name on most tools) is still accepted as
 a silent alias. (On `cerefox_get_audit_log` the entries filter, formerly `author`,
-is now `by_author`.) The primitive Edge Functions used by GPT Actions keep their
-original body fields (`requestor` on reads, `author` on ingest).
+is now `by_author`.) Since v1.13.2 the CLI (`--author` on every command,
+`--requestor` a hidden alias, `--by-author` the audit-list filter) and the
+primitive Edge Functions used by GPT Actions (`author` in every request body,
+`requestor` an alias, `by_author` on `cerefox-get-audit-log`) follow the same
+rule. (The HTTP API's headers are documented in [`api.md`](api.md): there
+`X-Cerefox-Author` and `X-Cerefox-Requestor` name the same actor.)
 
 You can optionally enforce caller identification so that tool calls must include
 an identity. Calls without one receive a JSON-RPC `-32602` error with a helpful

package/docs/guides/connect-agents.md

@@ -638,7 +638,7 @@ In the action editor, paste this schema (replace `<your-project-ref>`):
 openapi: 3.1.0
 info:
   title: Cerefox Knowledge Base
-  version: 3.4.1
+  version: 4.0.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -698,11 +698,12 @@ paths:
                     Whole results are dropped (never truncated mid-document) until
                     the budget is met; the response sets `truncated: true` when this
                     happens. Advanced; leave unset for the default.
-                requestor:
+                author:
                   type: string
                   description: >
-                    Name of the agent making this request (e.g., "ChatGPT").
-                    Recorded in the usage log for attribution. Optional.
+                    Your name (agent or user), e.g. "ChatGPT". Recorded in the
+                    usage log for attribution. Optional. `requestor` is still
+                    accepted as an alias.
       responses:
         '200':
           description: >
@@ -847,9 +848,11 @@ paths:
             schema:
               type: object
               properties:
-                requestor:
+                author:
                   type: string
-                  description: Name of the agent making this request. Optional.
+                  description: >
+                    Your name (agent or user). Recorded in the usage log.
+                    Optional. `requestor` is still accepted as an alias.
       responses:
         '200':
           description: Array of metadata keys with doc_count and example_values
@@ -875,9 +878,11 @@ paths:
                   description: >
                     UUID of a specific archived version to retrieve. Omit (or pass null)
                     for the current version. Version UUIDs are returned by listVersions.
-                requestor:
+                author:
                   type: string
-                  description: Name of the agent making this request. Optional.
+                  description: >
+                    Your name (agent or user). Recorded in the usage log.
+                    Optional. `requestor` is still accepted as an alias.
       responses:
         '200':
           description: >
@@ -905,9 +910,11 @@ paths:
                 document_id:
                   type: string
                   description: UUID of the document whose version history to list
-                requestor:
+                author:
                   type: string
-                  description: Name of the agent making this request. Optional.
+                  description: >
+                    Your name (agent or user). Recorded in the usage log.
+                    Optional. `requestor` is still accepted as an alias.
       responses:
         '200':
           description: >
@@ -929,9 +936,12 @@ paths:
                 document_id:
                   type: string
                   description: Filter by document UUID (optional)
-                author:
+                by_author:
                   type: string
-                  description: Filter by author name (optional)
+                  description: >
+                    Filter: only entries written by this author name (optional).
+                    Was `author` before v1.13.2; `author` is now the caller's
+                    identity here, as on every other operation.
                 operation:
                   type: string
                   description: >
@@ -949,9 +959,11 @@ paths:
                   type: integer
                   default: 50
                   description: Max entries to return (max 200)
-                requestor:
+                author:
                   type: string
-                  description: Name of the agent making this request. Optional.
+                  description: >
+                    Your name (agent or user). Recorded in the usage log.
+                    Optional. `requestor` is still accepted as an alias.
       responses:
         '200':
           description: >
@@ -969,9 +981,11 @@ paths:
             schema:
               type: object
               properties:
-                requestor:
+                author:
                   type: string
-                  description: Name of the agent making this request. Optional.
+                  description: >
+                    Your name (agent or user). Recorded in the usage log.
+                    Optional. `requestor` is still accepted as an alias.
       responses:
         '200':
           description: >
@@ -1028,9 +1042,11 @@ paths:
                   description: >
                     Response size budget in bytes when include_content is true
                     (whole results dropped to fit). Advanced; leave unset for the default.
-                requestor:
+                author:
                   type: string
-                  description: Name of the agent making this request. Optional.
+                  description: >
+                    Your name (agent or user). Recorded in the usage log.
+                    Optional. `requestor` is still accepted as an alias.
       responses:
         '200':
           description: >
@@ -1258,7 +1274,7 @@ You have access to a personal Cerefox knowledge base via a local CLI.
 Identify yourself on every call:
 - Writes (document ingest, document ingest-dir): pass --author "<your-name>" --author-type agent
 - Reads (search, document get, document version list, project list,
-  metadata search, audit list): pass --requestor "<your-name>"
+  metadata search, audit list): pass --author "<your-name>" (the same flag as on writes)
 
 When answering questions, search Cerefox first. When the user asks you to
 remember something, ingest it. Cite document titles for every claim drawn
@@ -1271,17 +1287,17 @@ The agent docs are written around MCP tool names. **CLI flag names match MCP par
 
 | MCP tool | CLI command |
 |---|---|
-| `cerefox_search` | `cerefox search "<query>" --match-count N --project-name <n> --metadata-filter '<json>' --requestor <name>` (CLI-only: `--mode`, `--alpha`, `--min-score`, `--only-metadata`) |
+| `cerefox_search` | `cerefox search "<query>" --match-count N --project-name <n> --metadata-filter '<json>' --author <name>` (CLI-only: `--mode`, `--alpha`, `--min-score`, `--only-metadata`) |
 | `cerefox_ingest` (file) | `cerefox document ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --source <s> --author <a> --author-type user\|agent` |
 | `cerefox_ingest` (paste) | `printf '...' \| cerefox document ingest --paste --title "<title>"` (same flags) |
-| `cerefox_get_document` | `cerefox document get <document-id> --version-id <vid> --requestor <name>` |
-| `cerefox_list_versions` | `cerefox document version list <document-id> --requestor <name>` |
-| `cerefox_list_projects` | `cerefox project list --requestor <name>` |
+| `cerefox_get_document` | `cerefox document get <document-id> --version-id <vid> --author <name>` |
+| `cerefox_list_versions` | `cerefox document version list <document-id> --author <name>` |
+| `cerefox_list_projects` | `cerefox project list --author <name>` |
 | `cerefox_set_document_metadata` | `cerefox document set-metadata <document-id> --set key=value` (also `--remove key`, `--json '{...}'`, `--replace`) |
 | `cerefox_set_document_projects` | `cerefox document set-projects <document-id> <name...> --author <a> --author-type user\|agent` (or `--clear`) |
 | `cerefox_list_metadata_keys` | `cerefox metadata keys` |
-| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --requestor <name>` |
-| `cerefox_get_audit_log` | `cerefox audit list --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --json --requestor <name>` |
+| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --author <name>` |
+| `cerefox_get_audit_log` | `cerefox audit list --document-id <id> --by-author <a> --operation <op> --since <iso> --until <iso> --limit N --json --author <name>` |
 
 > CLI verbs with no MCP equivalent: `cerefox document edit`, `cerefox project create` / `cerefox project edit`, `cerefox config list`.
 
@@ -1301,7 +1317,7 @@ After pointing your agent at the repo, ask it:
 ### Caveats
 
 - **Privilege level**: the CLI uses the **service-role key** (`CEREFOX_SUPABASE_KEY`), which bypasses Row Level Security. An agent with Bash access has the same full read/write power you do. Only enable Path C for agents you trust to act on your behalf — the same trust level you'd grant Cursor/Claude Code for editing your source code.
-- **Audit attribution**: Path C records `access_path = "cli"` in usage logs, distinct from `"local-mcp"` / `"remote-mcp"`. **Agents must set `--author <name> --author-type agent` on writes and `--requestor <name>` on reads** (or rely on `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` env vars). Without these flags, writes attribute to `"unknown"` / `"user"`, which under-reports agent activity. See the 2026-05-18 Decision Log Q2 entry for the design rationale (`author_type` is caller-declared on ambiguous channels — CLI and Edge Functions — but `access_path` is always derived from the code layer).
+- **Audit attribution**: Path C records `access_path = "cli"` in usage logs, distinct from `"local-mcp"` / `"remote-mcp"`. **Agents must set `--author <name> --author-type agent` on writes and `--author <name>` on reads** (or rely on `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` env vars). Without these flags, writes attribute to `"unknown"` / `"user"`, which under-reports agent activity. See the 2026-05-18 Decision Log Q2 entry for the design rationale (`author_type` is caller-declared on ambiguous channels — CLI and Edge Functions — but `access_path` is always derived from the code layer).
 - **Soft-delete and restore are reachable; permanent purge is not** — by design. `cerefox document delete` / `cerefox document restore` on the CLI, `cerefox_delete_document` / `cerefox_restore_document` over MCP (v1.7.0, #208/#210): both audited with author attribution. **Permanent purge** (irreversible) stays web-UI-only with human-in-the-loop confirmation. If an agent deletes or restores content, it should surface that to the user explicitly so they can follow it in the audit trail. See [`access-paths.md` → Destructive operations and the trust model](access-paths.md#destructive-operations-and-the-trust-model) for the full rationale and contributor guidance.
 - **Cross-doc links in content you ingest** become clickable when the user views them in the Cerefox web UI. **Always author them as `[Text](uuid)`** — the server validates these on every write (v1.7.0) and rejects links to nonexistent ids, which catches mangled UUIDs at write time. `[Text](docs/path.md)` exists for repo-ingested files; do not write title-based links (fragile, and `AGENT_GUIDE.md` says never in agent-authored content). See [`AGENT_GUIDE.md` → "Writing linkable content"](../../AGENT_GUIDE.md#writing-linkable-content) for the full set of rules.
 - **CLI install per machine**: the agent needs the `cerefox` binary installed (`npm install -g @cerefox/memory`) with a resolvable `.env`. If you skip the local install entirely, Path A-Remote or Path B is the only option.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "Cerefox — user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",