@cerefox/memory 0.4.3 → 0.5.0

package/AGENT_GUIDE.md

@@ -0,0 +1,462 @@
+# How AI Agents Use Cerefox
+
+Reference guide for AI agents interacting with the Cerefox knowledge base.
+Read this before your first interaction. For a minimal quick reference, see `AGENT_QUICK_REFERENCE.md`.
+
+---
+
+## What Cerefox Is
+
+Cerefox is a persistent, shared knowledge base that multiple AI agents can read and write.
+Knowledge written by one agent (or a human) is immediately searchable by any other agent.
+It is not a message bus -- it is curated, versioned, searchable memory backed by Postgres + pgvector.
+
+## Two ways to interact with Cerefox
+
+You'll be using **one** of these — whichever your user (or the harness) has configured:
+
+1. **MCP tools (default)** — ten named tools (`cerefox_search`, `cerefox_ingest`, …, `cerefox_get_help`) exposed by either a local MCP server (`@cerefox/memory` via npm, or `cerefox mcp` as a soft wrapper) or the remote `cerefox-mcp` Edge Function. Tool names and parameters are documented in **The 10 Tools** below. This is the recommended path for purpose-built agent clients.
+2. **Shell CLI (Bash tool)** — the same operations exposed as a local `uv run cerefox …` command, invoked via your Bash tool. Used when your user prefers not to install/configure an MCP server. The semantics are identical; only the surface differs. See **Using Cerefox via the CLI** near the bottom of this guide for the MCP-tool → CLI-command mapping and the small list of behavioural differences.
+
+If you're not sure which mode you're in: check whether `cerefox_search` shows up in your tool list. If yes, use MCP. If no, ask your user where the Cerefox checkout lives — they'll have told you, typically in `CLAUDE.md`, `AGENTS.md`, or an equivalent project memory file.
+
+The rest of this guide is written around the MCP tool names, since those are stable across both modes. The CLI section maps each tool name to its CLI command.
+
+### Self-help via MCP
+
+If you have MCP access and you're uncertain about any convention in this guide, call **`cerefox_get_help`** — it returns the contents of `AGENT_QUICK_REFERENCE.md` (the same conventions, rules, and workflow snippets) as MCP-native text, no file-system reads required.
+
+- No arguments → full reference + an index of `## H2` topics.
+- `topic: "tools"` (or any case-insensitive H2 substring) → just that section.
+- `topic: "made-up-name"` → an "unknown topic" message plus the available-topics list.
+
+The tool is intentionally MCP-only so an agent that has been dropped into Cerefox without filesystem access (e.g. a remote MCP client) can still bootstrap its own conventions. Treat it as a fallback: this guide and `AGENT_QUICK_REFERENCE.md` are the canonical surface; `cerefox_get_help` is the in-band escape hatch.
+
+---
+
+## The 10 Tools
+
+### cerefox_search
+
+Find documents using hybrid search (full-text + semantic vector similarity).
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `query` | Yes | Natural language search query. 3-8 focused keywords work best. |
+| `match_count` | No | Max documents to return (default 5). |
+| `project_name` | No | Filter to a specific project by name. |
+| `metadata_filter` | No | JSON object for filtering by metadata (AND semantics). Example: `{"type": "decision-log"}` |
+| `max_bytes` | No | Response size budget in bytes (default 200000). |
+| `requestor` | No | Your agent name for attribution. Always set this. |
+
+**Results format**: Each result shows `## Title [id: <uuid>] (score: X.XXX)` followed by content.
+Save the `document_id` from `[id: ...]` -- you need it for `cerefox_get_document` and `cerefox_ingest` updates.
+
+For large documents, results may be partial (`is_partial` flag). Use `cerefox_get_document` with the ID to get the full text.
+
+**Rule**: Always search before answering questions about stored knowledge. Always search before ingesting to check for duplicates.
+
+---
+
+### cerefox_ingest
+
+Save a new document or update an existing one.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `title` | Yes | Descriptive, stable title (e.g., "OAuth 2.1 Design Document", not "doc1"). |
+| `content` | Yes | Markdown content. Use H1/H2/H3 headings -- the chunker uses them for segmentation. |
+| `document_id` | No | UUID of an existing document to update. When provided, updates that document directly regardless of `update_if_exists`. Returns an error if the document does not exist. Workflow: search → note the `[id: ...]` → pass here. |
+| `update_if_exists` | No | When `true`, updates the document with the same title (versions the old content). Default `false`. Ignored when `document_id` is provided. |
+| `project_name` | No | **Single** project name (created if absent). On update: **non-destructive add** — ensures this membership exists, preserves others. See "Project membership semantics" below. |
+| `project_names` | No | **List** of project names (each created if absent). On update: **destructive replace** — sets the document's full project set to exactly this list. Use when you want to set multiple projects at once, or deliberately change the membership list. Wins over `project_name` when both are passed. |
+| `metadata` | No | Arbitrary JSON. Use at minimum: `type` and `status`. |
+| `author` | No | Your agent name for audit attribution. Always set this. |
+| `source` | No | Origin label (default "agent"). |
+
+**The update workflow (preferred -- ID-based)**:
+1. Search for the document. Note the `[id: abc123]` in the result.
+2. Call `cerefox_ingest` with `document_id: "abc123"` and the new content.
+3. The old content is automatically versioned and recoverable.
+
+**The update workflow (fallback -- title-based)**:
+1. Search for the document first.
+2. Call `cerefox_ingest` with the **exact same title** and `update_if_exists: true`.
+3. If you use a different title, a **new** document is created (the old one remains). This is almost never what you want when revising.
+
+**Deduplication**: Content is SHA-256 hashed. Identical content is skipped (no re-indexing). Metadata-only changes update metadata without creating a version.
+
+**What to ingest**: Distilled summaries, decisions with rationale, curated insights. Not raw dumps, logs, or transcripts. Use Markdown headings for structure.
+
+#### Project membership semantics
+
+This is subtle but important — a document can belong to multiple projects (many-to-many), and an operator may have curated the project list via the web UI. **You must not silently strip their work when updating content.** The rules:
+
+| What you pass on update | What happens to memberships |
+|---|---|
+| `project_name: "X"` (singular) | **Non-destructive add.** Ensures the doc is in project X. Other memberships untouched. |
+| `project_names: ["X", "Y"]` (list) | **Destructive replace.** Sets the doc's project set to exactly `{X, Y}`. Other memberships are removed. Use when you want this. |
+| Neither | **No change** to project memberships. |
+
+**Rule of thumb**: if you just want to ensure a doc is *associated with* a project, use singular `project_name`. If you want to *change* the project list, use `project_names`. If you don't know — use singular. When in doubt, use the dedicated `cerefox_set_document_projects` tool, which makes the destructive replace intent explicit and doesn't require also writing content.
+
+---
+
+### cerefox_get_document
+
+Retrieve the complete text of a document by its UUID.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `document_id` | Yes | UUID from search results `[id: ...]`. |
+| `version_id` | No | UUID of an archived version (from `cerefox_list_versions`). |
+| `requestor` | No | Your agent name. |
+
+Use this when search returns partial results, or to read a previous version before restoring it.
+
+---
+
+### cerefox_list_versions
+
+Show version history of a document.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `document_id` | Yes | UUID of the document. |
+| `requestor` | No | Your agent name. |
+
+Returns: version_number, version_id, source, chunk_count, total_chars, created_at.
+
+**To restore an old version**: retrieve it with `cerefox_get_document(document_id, version_id=<target>)`, then re-ingest with `cerefox_ingest(title=<same>, content=<old>, update_if_exists=true)`.
+
+---
+
+### cerefox_list_metadata_keys
+
+Discover which metadata keys are in use across the knowledge base.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `requestor` | No | Your agent name. |
+
+Returns each key with document count and example values. Call this before constructing `metadata_filter` for search.
+
+---
+
+### cerefox_metadata_search
+
+Find documents by metadata criteria without a text search query.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `metadata_filter` | Yes | JSON key-value pairs (AND semantics). Example: `{"type": "decision-log"}` |
+| `project_name` | No | Restrict to a project. |
+| `include_content` | No | Include full text (default false). |
+| `limit` | No | Max results (default 10). |
+| `updated_since` | No | ISO-8601 timestamp. Only docs updated on/after. |
+| `created_since` | No | ISO-8601 timestamp. Only docs created on/after. |
+| `max_bytes` | No | Response size budget when include_content is true. |
+| `requestor` | No | Your agent name. |
+
+Use for browsing by category, catching up on recent changes (`updated_since`), or finding all documents of a specific type.
+
+---
+
+### cerefox_list_projects
+
+List all projects with names, IDs, and descriptions.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `requestor` | No | Your agent name. |
+
+Call once per session to discover available projects before filtering search results by `project_name`.
+
+---
+
+### cerefox_set_document_projects
+
+Set the document's project memberships to EXACTLY the given list. **Destructive replace.** Any existing memberships not in the list are removed. Content is untouched. Logged as `update-metadata` in the audit log.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `document_id` | Yes | UUID of the document. Get from a prior `cerefox_search` result (the `[id: ...]` tag). |
+| `project_names` | Yes | Explicit list of project names. Each created if absent (case-insensitive lookup). Empty list = clear all memberships. Order is preserved. |
+| `author` | No | Your agent name for audit attribution. |
+
+**Use cases**:
+- You want to change project membership without rewriting the document body. This tool is faster and clearer than calling `cerefox_ingest` again.
+- You want to add a doc to multiple projects in one call (cleaner than N separate `cerefox_ingest` calls).
+- You want to *remove* a project from a doc's set (use the list of remaining projects without the one to drop).
+- An operator asked you to consolidate or clean up a doc's project list.
+
+**Use `cerefox_ingest` with `project_names` instead** if you're updating the content anyway — same destructive-replace semantics, one call instead of two.
+
+**Never use this tool to "just ensure X is in the list"** — that's what `cerefox_ingest` with singular `project_name` does, non-destructively. If you call this tool with only one name, you will REMOVE the document from every other project it was in.
+
+---
+
+### cerefox_get_audit_log
+
+Query the immutable audit log of all write operations.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `document_id` | No | Filter by document UUID. |
+| `author` | No | Filter by author name. |
+| `operation` | No | Filter by type: create, update-content, update-metadata, delete, restore. |
+| `since` | No | ISO timestamp lower bound. |
+| `limit` | No | Max entries (default 50, max 200). |
+| `requestor` | No | Your agent name. |
+
+---
+
+### cerefox_get_help
+
+Retrieve Cerefox conventions and quick reference content over MCP — the same content as `AGENT_QUICK_REFERENCE.md` in the repo. Designed for agents who lack filesystem access (remote MCP) or just want an in-band refresher.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `topic` | No | Case-insensitive substring match against `## H2` section titles. Omit to get the full reference plus a section index. |
+| `requestor` | No | Your agent name (recorded with `access_path = "remote-mcp"` or `"local-mcp"`). |
+
+**Behaviour:**
+- No `topic` → full quick-reference markdown + an `## Available topics` index.
+- `topic: "tools"` → just the `## Tools` section (no index footer).
+- `topic` matches nothing → `No help topic matched "<topic>"` + available-topics list.
+
+Cheap and idempotent. Call it any time you're uncertain about a convention (link forms, project-membership semantics, identity flags, etc.).
+
+---
+
+## Key Workflows
+
+### Search then update (ID-based -- preferred)
+
+```
+1. cerefox_search("topic")           -- find relevant docs, note [id: uuid]
+2. cerefox_get_document(id)          -- get full text if partial
+3. cerefox_ingest(title, content,    -- update by document ID (deterministic)
+     document_id="uuid")
+```
+
+### Search then update (title-based -- fallback)
+
+```
+1. cerefox_search("topic")           -- find relevant docs
+2. cerefox_get_document(id)          -- get full text if partial
+3. cerefox_ingest(title, content,    -- update with same title
+     update_if_exists=true)
+```
+
+### Save new knowledge
+
+```
+1. cerefox_search("topic")           -- check if it already exists
+2. If not found: cerefox_ingest(title, content, project_name, metadata)
+3. If found: cerefox_ingest(same_title, new_content, document_id="uuid")
+```
+
+### Catch up on recent changes
+
+```
+1. cerefox_metadata_search(metadata_filter={"type": "decision-log"},
+     updated_since="2026-03-28T00:00:00Z")
+2. Review what other agents or the user have written since your last session
+```
+
+---
+
+## Rules
+
+1. **Always search before ingesting.** Check for existing documents on the topic.
+2. **Prefer `document_id` for updates** -- pass the UUID from search results to update a specific document. Use `update_if_exists: true` as a fallback when you don't have the ID.
+3. **Always set `author`/`requestor`** to your agent name for attribution.
+4. **Use the `document_id` from search results** for `cerefox_get_document`, `cerefox_list_versions`, and targeted `cerefox_ingest` updates.
+5. **Add metadata**: at minimum `type` (e.g., "research", "decision-log") and `status` ("active", "draft").
+6. **Write structured Markdown** with H1/H2/H3 headings. The chunker uses heading structure.
+7. **Distill, don't dump.** Summaries > transcripts. Decisions > discussions. Insights > raw data.
+
+---
+
+## Metadata Conventions
+
+| Key | Purpose | Example values |
+|-----|---------|---------------|
+| `type` | Document category | `decision-log`, `design-doc`, `research`, `agent-guide`, `vision-document` |
+| `status` | Lifecycle state | `active`, `draft`, `archived`, `research-complete` |
+| `author` | Creator name | `claude-code`, `archiver`, `user` |
+| `tags` | Topic keywords (JSON array string) | `["architecture", "MCP", "memory"]` |
+
+Call `cerefox_list_metadata_keys` for the current list -- conventions evolve.
+
+---
+
+## Writing linkable content
+
+Documents you ingest may contain markdown links to other Cerefox documents. The Cerefox web UI intercepts these links at click time and resolves them to the target document. The resolution happens entirely in the browser; the stored markdown is untouched.
+
+### The rule for agents: use document UUIDs
+
+**For any cross-reference you author, use the target document's UUID.** Period.
+
+```markdown
+[Opportunity Index](c937b70f-77af-43d3-b9bc-9f31e0d2041d)
+```
+
+UUIDs are the only link form that is fully reliable:
+
+- **Stable**: survives title changes. If the target gets renamed, the link still resolves.
+- **Unambiguous**: a UUID matches exactly one document. No "multiple matches" popover, no surprise navigations.
+- **Encoding-safe**: no spaces, no colons, no parentheses, no characters that the markdown parser, URL sanitizer, or HTML attribute layer will trip over.
+- **Discoverable**: every `cerefox_search` result includes `[id: <uuid>]` after the title. Every `cerefox_ingest` response returns the document_id. **Capture and use these IDs.**
+
+### Workflow
+
+```
+1. cerefox_search "topic"  →  result includes [id: abc123]
+2. In your written content, link as: [Topic Name](abc123)
+3. Done.
+```
+
+If you're writing about a document you haven't searched for yet, search for it first, grab the ID, then write the link. Don't guess by title — searching costs one tool call and gives you the stable link form.
+
+### Other link forms (best-effort, NOT for agent-authored content)
+
+The resolver also accepts three other link forms, but **agents should not write them**. They exist primarily for repo-ingested files (where the source markdown naturally uses paths) and as best-effort fallbacks for legacy or human-authored content.
+
+| Form | Example | Reliable for agents? |
+|---|---|---|
+| Repo-relative path | `[Quickstart](docs/guides/quickstart.md)` | Only when the target has a `source_path` from repo ingest. Don't construct manually. |
+| Basename only | `[Quickstart](quickstart.md)` | Same — best-effort path fallback. Don't construct manually. |
+| Angle-bracket title | `[Career Coach](<Career Coach: Lisa Nichols>)` | **Fragile**. Breaks on titles containing colons, parentheses, ampersands, brackets, or other punctuation. Web UI's URL sanitizer strips suspicious-looking URLs (e.g. anything before a `:` that looks like a scheme) → link silently navigates to current page. **Never use this form in agent-authored content.** |
+
+If you're tempted to write `[Title With Spaces](<Title With Spaces>)` because you don't have the ID, **do an extra `cerefox_search` and use the ID instead**. The one extra tool call is much cheaper than the user encountering a broken link.
+
+### Always set meaningful link text
+
+The `[Link Text](target)` syntax has two halves:
+
+- **Link text** (`[…]`): what the human reader sees. Use the actual title.
+- **Target** (`(…)`): what the resolver consumes. Always a UUID for agent-authored content.
+
+Bad: `[c937b70f-77af-...](c937b70f-77af-...)` — opaque to the reader.
+Good: `[Job Hunting - Opportunity Index](c937b70f-77af-43d3-b9bc-9f31e0d2041d)`.
+
+### What you don't need to do
+
+- **You don't need to escape `#` anchors.** `[Section](abc123#configuration)` works — the resolver splits the anchor off and reattaches it to the target document URL.
+- **You don't need to handle external URLs.** Links starting with `http://`, `https://`, `mailto:`, etc. pass through unchanged and open in a new tab.
+- **You don't need to handle absolute SPA paths.** Links starting with `/` (e.g. `/search?q=foo`) pass through to the SPA router unchanged.
+- **You don't need to create relation rows** for these links. The resolver does not populate the relation graph at this stage — that's a separate, future feature. If you want explicit relations between documents, use `cerefox_set_relation` when it ships.
+
+### A note on agents on Path C (CLI via Bash tool)
+
+If you're using Cerefox via the local CLI (Path C from `connect-agents.md`), the same writing conventions apply. The web UI is where resolution happens; the CLI is just how you wrote the content. A user reading your ingested document later in the web UI gets clickable behaviour for free — **as long as you authored the links by UUID**.
+
+---
+
+## Governance
+
+- **Review status**: agent writes set `pending_review`; human edits set `approved`. Both are searchable.
+- **Soft delete**: deleted documents go to trash (recoverable). They are excluded from search. You can soft-delete via MCP (`cerefox_delete_document` if your client exposes it) or CLI (`cerefox delete-doc --yes --author <you> --author-type agent`).
+- **Permanent purge and restore-from-trash are web-UI-only**, by design. If you decide to delete something, **tell the user explicitly** that you soft-deleted it and that they can review or restore it via the Cerefox web UI. You cannot un-do your own soft-delete from agent code; only the human can. See [`docs/guides/access-paths.md` → Destructive operations and the trust model](docs/guides/access-paths.md#destructive-operations-and-the-trust-model).
+- **Versioning**: every update via `update_if_exists` creates an archived version. Old content is always recoverable.
+- **Audit log**: all write operations are recorded with author, timestamp, and size changes.
+
+This is a human-on-the-loop model: agents write and soft-delete freely with full audit attribution; humans review the trash, restore mistakes, and decide when to purge.
+
+---
+
+## Using Cerefox via the CLI
+
+Read this section only if you do **not** have MCP tools available (no `cerefox_search` in your tool list) and your user has pointed you at a local Cerefox checkout. The semantics of every operation are identical to MCP — only the calling surface differs. The conventions above (when to search, when to ingest, metadata rules, ID-based update workflow, governance) all still apply.
+
+### Setup
+
+Your user will have told you where their Cerefox checkout lives (commonly `/Users/<name>/src/cerefox`, but check `CLAUDE.md` / `AGENTS.md` / project memory for the exact path). Run every command from that directory, or use `cd /path/to/cerefox && uv run cerefox …` in your Bash tool call.
+
+If a command fails with `command not found: cerefox`, run it as `uv run cerefox <subcommand>` (the project's `uv` environment provides the binary).
+
+> Full per-flag reference lives in [`docs/guides/cli.md`](docs/guides/cli.md). The mapping table below is the agent-facing summary. **CLI flag names match MCP parameter names exactly** (kebab-case); short forms like `--project`, `--filter`, `--count`, `--update`, `--version` are accepted as aliases.
+
+### MCP tool ↔ CLI command mapping
+
+| MCP tool | CLI command |
+|---|---|
+| `cerefox_search(query, match_count, project_name, metadata_filter, requestor)` | `uv run cerefox search "<query>" --match-count N --project-name <n> --metadata-filter '<json>' --requestor <name>` (also `--mode`, `--alpha`, `--min-score` — CLI-only) |
+| `cerefox_ingest(title, content, project_name, metadata, update_if_exists, document_id, source, author, author_type)` (file) | `uv run cerefox 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 '%s' "<content>" \| uv run cerefox ingest --paste --title "<title>"` (same flags) |
+| `cerefox_get_document(document_id, version_id, requestor)` | `uv run cerefox get-doc <document-id> --version-id <vid> --requestor <name>` |
+| `cerefox_list_versions(document_id, requestor)` | `uv run cerefox list-versions <document-id> --requestor <name>` |
+| `cerefox_list_projects(requestor)` | `uv run cerefox list-projects --requestor <name>` |
+| `cerefox_list_metadata_keys()` | `uv run cerefox list-metadata-keys` |
+| `cerefox_metadata_search(metadata_filter, project_name, updated_since, created_since, limit, include_content, requestor)` | `uv run 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, author, operation, since, until, limit, requestor)` | `uv run cerefox get-audit-log --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --json --requestor <name>` |
+
+### Caller-identity flags (set these the same way you would on MCP)
+
+You **MUST** identify yourself on every CLI invocation, exactly as you do via MCP:
+
+- **Writes** (`ingest`, `ingest-dir`): set `--author "<your-agent-name>" --author-type "agent"`. The `author_type=agent` value auto-routes the write to `pending_review` (governance signal), matching the MCP path.
+- **Reads** (`search`, `get-doc`, `list-versions`, `list-projects`, `metadata-search`, `get-audit-log`): set `--requestor "<your-agent-name>"`.
+
+Alternative: have your user set `CEREFOX_AUTHOR_NAME`, `CEREFOX_AUTHOR_TYPE`, `CEREFOX_REQUESTOR_NAME` in their `.env` once. The CLI picks them up automatically — see [`docs/guides/cli.md`](docs/guides/cli.md) for the precedence rules.
+
+### Behavioural differences worth knowing
+
+1. **CLI output is human-formatted by default.** `cerefox search` returns a numbered, indented text block with title, score, and a 300-char preview per result. To extract document IDs reliably, parse the `Doc: <title>  (<source>)` lines or fall back to `cerefox list-docs` for a clean tabular listing. `cerefox get-doc <id>` prints raw Markdown to stdout. **For scripted access to audit data**, use `cerefox get-audit-log --json` — one JSON object per line, ideal for piping to `jq`.
+
+2. **Every invocation is independent.** With MCP, your tool framework can pass `requestor` once per session. With the CLI, every command is a separate process — pass `--requestor` / `--author` / `--author-type` on every relevant invocation, or set the env-var defaults once at the start.
+
+3. **Errors come back on stderr with a non-zero exit code.** Check both — a successful command prints results on stdout and exits 0; a failure prints to stderr and exits non-zero.
+
+### Quick patterns
+
+**Search before answering:**
+```bash
+uv run cerefox search "OAuth design notes" --match-count 5 --requestor "claude-code"
+```
+
+**Search then read full content of a hit:**
+```bash
+uv run cerefox search "OAuth design" --match-count 3 --requestor "claude-code"
+# Note the [n] entries. Pick one and grab the doc id from `list-docs` or the result preview.
+uv run cerefox get-doc <document-id> --requestor "claude-code"
+```
+
+**Ingest a note (agent identity):**
+```bash
+printf '# Title\n\nBody markdown with H2s for chunking.\n' \
+  | uv run cerefox ingest --paste \
+      --title "Stable Title" \
+      --project-name "Cerefox" \
+      --metadata '{"type":"decision-log","status":"active"}' \
+      --author "claude-code" --author-type "agent"
+```
+
+**ID-based update (preferred — deterministic):**
+```bash
+# Step 1: search and note the [id: abc12345-...] in the result
+uv run cerefox search "the exact doc" --match-count 1 --requestor "claude-code"
+
+# Step 2: update by ID
+printf '...new content...' \
+  | uv run cerefox ingest --paste \
+      --title "Exact Same Title" \
+      --document-id "abc12345-..." \
+      --author "claude-code" --author-type "agent"
+```
+
+**Title-based update (fallback when ID isn't available):**
+```bash
+printf '...new content...' \
+  | uv run cerefox ingest --paste --title "Exact Same Title" --update-if-exists \
+      --author "claude-code" --author-type "agent"
+```
+
+**Audit-log access (scripted, JSON):**
+```bash
+uv run cerefox get-audit-log --json --limit 1000 --requestor "claude-code" \
+  | jq 'select(.author_type == "agent")'
+```

package/AGENT_QUICK_REFERENCE.md

@@ -0,0 +1,76 @@
+# Cerefox Knowledge Base -- Agent Quick Reference
+
+Cerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for "How AI Agents Use Cerefox" or call `cerefox_get_help` to retrieve this content over MCP.
+
+## Tools
+
+| Tool | Purpose | Key params |
+|------|---------|------------|
+| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |
+| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |
+| `cerefox_get_document` | Get full document by ID | `document_id` (required) |
+| `cerefox_list_versions` | Version history of a document | `document_id` (required) |
+| `cerefox_metadata_search` | Find docs by metadata (no text query) | `metadata_filter` (required), `include_content`, `updated_since` |
+| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |
+| `cerefox_list_projects` | List all projects | (none required) |
+| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |
+| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |
+| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |
+
+## Essential Rules
+
+1. **Search before ingesting** -- check if the document exists first.
+2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.
+3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.
+4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.
+5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").
+6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.
+7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.
+8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.
+9. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.
+
+## Update Workflow (ID-based -- preferred)
+
+```
+search("topic") -> find doc [id: abc123] -> get_document(abc123) -> modify ->
+ingest(title="Same Title", content="...", document_id="abc123", author="my-agent")
+```
+
+## Update Workflow (title-based -- fallback)
+
+```
+search("topic") -> find doc -> modify ->
+ingest(title="Same Title", content="...", update_if_exists=true, author="my-agent")
+```
+
+## Catch-Up Workflow
+
+```
+metadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")
+```
+
+## CLI fallback (when MCP is unavailable)
+
+If `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. From v0.5+ the canonical invocation is plain **`cerefox <subcommand>`** (installed via `npm install -g @cerefox/memory`). The legacy `uv run cerefox <subcommand>` (Python CLI in a Cerefox checkout) still works through v0.7 but emits a deprecation banner.
+
+Same operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); short forms (`--filter`, `--project`, `--count`, `--update`, `--version`) work as aliases.
+
+| MCP tool | CLI (v0.5+ canonical) |
+|---|---|
+| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |
+| `cerefox_ingest` (paste) | `printf '...' \| cerefox ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |
+| `cerefox_ingest` (update by ID) | `printf '...' \| cerefox ingest --paste --title "<t>" --document-id "<uuid>" --author "<your-name>" --author-type agent` |
+| `cerefox_get_document` | `cerefox get-doc <id> --version-id <vid> --requestor "<your-name>"` |
+| `cerefox_list_versions` | `cerefox list-versions <id> --requestor "<your-name>"` |
+| `cerefox_list_projects` | `cerefox list-projects --requestor "<your-name>"` |
+| `cerefox_list_metadata_keys` | `cerefox list-metadata-keys` |
+| `cerefox_metadata_search` | `cerefox metadata-search --metadata-filter '<json>' --requestor "<your-name>"` |
+| `cerefox_set_document_projects` | _MCP-only; a CLI command will be added in a future release. Until then, run via MCP if available._ |
+| `cerefox_get_audit_log` | `cerefox get-audit-log --requestor "<your-name>"` (add `--json` for scripted access) |
+| `cerefox_get_help` | `cerefox docs agent-quick-reference --print` (or `cerefox docs --list` for the full bundled-docs index) |
+
+**Set identity on every call**, exactly as you would on MCP:
+- Writes (`ingest`, `ingest-dir`): `--author "<your-name>" --author-type agent`
+- Reads: `--requestor "<your-name>"`
+
+Or have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.