@romiluz/clawmongo 2026.3.26 → 2026.3.28

package/docs/reference/clawmongo-vs-default-memory.md

@@ -25,11 +25,11 @@ Both are valid choices. The default memory is simpler to set up. ClawMongo is mo
 | **Retrieval paths**        | 1 (search)                                                 | 8 (active-critical, procedural, structured, raw-window, graph, episodic, kb, hybrid) |
 | **Retrieval planning**     | Simple search dispatch                                     | Pure-function planner scoring paths based on query analysis                          |
 | **Reranking**              | MMR (Maximal Marginal Relevance)                           | Source diversity penalty + episode boost + deduplication                             |
-| **Schema validation**      | None                                                       | JSON Schema (`$jsonSchema`) on 17 collections                                        |
+| **Schema validation**      | None                                                       | JSON Schema (`$jsonSchema`) on 19 collections                                        |
 | **Multi-tenant isolation** | Filesystem separation                                      | Compound indexes with `agentId` prefix                                               |
 | **Cross-instance sync**    | File sync (rsync, git)                                     | MongoDB replica set + change streams                                                 |
 | **Operational visibility** | Limited                                                    | Ingest runs, projection runs, relevance telemetry (3 collections)                    |
-| **Data model**             | Flat files + SQLite rows                                   | 20 collections, 53 standard indexes, up to 8 search indexes                          |
+| **Data model**             | Flat files + SQLite rows                                   | 23 collections, 66 standard indexes, up to 9 search indexes                          |
 | **Entity extraction**      | None                                                       | Rule-based from conversations (@mentions, #tags, URLs, paths, quoted names)          |
 | **Graph traversal**        | None                                                       | `$graphLookup` with `restrictSearchWithMatch` for tenant isolation                   |
 | **Memory lifecycle**       | Manual                                                     | TTL indexes for caches/telemetry, consolidation lifecycle for events                 |

package/docs/reference/heart-brain-boundary.md

@@ -16,18 +16,18 @@ The contract is:
 
 - Workspace markdown defines who the agent is.
 - MongoDB defines what the agent can remember and retrieve.
-- `MEMORY.md` and `memory/*.md` are the bridge between the two.
+- `memory/*.md` files are the bridge between the two.
 
 This boundary is not optional. If the boundary drifts, ClawMongo stops being
 OpenClaw with a MongoDB-first memory system and becomes a competing agent model.
 
 ## Ownership map
 
-| Layer  | Authority                               | Allowed data                                                   | Must not own                                    |
-| ------ | --------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------- |
-| Heart  | Workspace bootstrap markdown            | identity, persona, rules, operator guidance, startup cadence   | structured facts, KB docs, retrieval indexes    |
-| Bridge | `MEMORY.md`, `memory.md`, `memory/*.md` | operator-authored notes, informal observations, daily logs     | identity canon, DB-native structured records    |
-| Brain  | MongoDB                                 | recall, sessions, KB, structured memory, retrieval diagnostics | persona, bootstrap policy, agent identity canon |
+| Layer  | Authority                    | Allowed data                                                   | Must not own                                    |
+| ------ | ---------------------------- | -------------------------------------------------------------- | ----------------------------------------------- |
+| Heart  | Workspace bootstrap markdown | identity, persona, rules, operator guidance, startup cadence   | structured facts, KB docs, retrieval indexes    |
+| Bridge | `memory/*.md`                | operator-authored notes, informal observations, daily logs     | identity canon, DB-native structured records    |
+| Brain  | MongoDB                      | recall, sessions, KB, structured memory, retrieval diagnostics | persona, bootstrap policy, agent identity canon |
 
 ## Heart files
 
@@ -58,8 +58,6 @@ Rules:
 
 These files remain human-authored markdown and may be synchronized into MongoDB:
 
-- `MEMORY.md`
-- `memory.md`
 - `memory/*.md`
 
 Rules:
@@ -103,8 +101,8 @@ These invariants should hold for every ClawMongo release:
 
 1. `src/agents/workspace.ts` stays aligned with upstream OpenClaw for the
    canonical bootstrap file set unless a change is explicitly justified.
-2. `src/memory/internal.ts` must continue to treat only `MEMORY.md`, `memory.md`,
-   and `memory/` as default memory corpus paths.
+2. `src/memory/internal.ts` must continue to treat only `memory/` as the default
+   memory corpus path (root `MEMORY.md` is deprecated).
 3. `src/agents/system-prompt.ts` may add a MongoDB routing bridge, but that
    bridge must not replace the heart-file roles defined above.
 4. `memory_search` may search across bridge files, sessions, KB, and structured

package/docs/reference/memory-config.md

@@ -59,7 +59,7 @@ Set `memory.backend = "mongodb"` (this is the default and only valid value).
 
 - **Canonical events**: Conversation turns persist directly to the `events` collection via `persistConversationMessageToMongo`. No disk intermediary.
 - **Chunk projection**: Events are projected into searchable chunks in the `chunks` collection.
-- **Bridge sync**: Workspace Markdown files (`MEMORY.md`, `memory/**/*.md`) are synced to MongoDB chunks for hybrid retrieval.
+- **Bridge sync**: Workspace Markdown files (`memory/**/*.md`) are synced to MongoDB chunks for hybrid retrieval.
 - **Vector search**: Handled by mongot (Atlas Search) with `$vectorSearch`. Automated embeddings via Voyage AI generate vectors at index-time and query-time.
 - **Text search**: `$text` indexes provide BM25 keyword search as a fallback when vector search is unavailable.
 - **Hybrid search**: `$rankFusion` / `$scoreFusion` combine vector and keyword results when both are available.
@@ -146,7 +146,7 @@ Notes:
 - Paths can be absolute or workspace-relative.
 - Directories are scanned recursively for `.md` files.
 - By default, only Markdown files are indexed.
-- If `memorySearch.multimodal.enabled = true`, OpenClaw also indexes supported image/audio files under `extraPaths` only. Default memory roots (`MEMORY.md`, `memory.md`, `memory/**/*.md`) stay Markdown-only.
+- If `memorySearch.multimodal.enabled = true`, OpenClaw also indexes supported image/audio files under `extraPaths` only. Default memory roots (`memory/**/*.md`) stay Markdown-only.
 - Symlinks are ignored (files or directories).
 
 ## Multimodal memory files (Gemini image + audio)
@@ -306,7 +306,7 @@ agents: {
 ## What gets indexed (and when)
 
 - **Canonical events**: Written directly to MongoDB on the runtime write path. No disk intermediary.
-- **Bridge sync**: Markdown files (`MEMORY.md`, `memory/**/*.md`) are synced to MongoDB chunks for hybrid retrieval. Watcher marks dirty (debounce 1.5s), sync runs asynchronously.
+- **Bridge sync**: Markdown files (`memory/**/*.md`) are synced to MongoDB chunks for hybrid retrieval. Watcher marks dirty (debounce 1.5s), sync runs asynchronously.
 - **Chunk projection**: Canonical events are projected into searchable chunks for retrieval.
 - **Reindex triggers**: The index stores the embedding **provider/model + endpoint fingerprint + chunking params**. If any change, ClawMongo automatically resets and reindexes.
 
@@ -451,7 +451,6 @@ With the default half-life of 30 days:
 
 **Evergreen files are never decayed:**
 
-- `MEMORY.md` (root memory file)
 - Non-dated files in `memory/` (e.g., `memory/projects.md`, `memory/network.md`)
 - These contain durable reference information that should always rank normally.
 

package/docs/reference/mongodb-capabilities.md

@@ -1,6 +1,6 @@
 # MongoDB Capabilities in ClawMongo
 
-ClawMongo uses 12 MongoDB capabilities that together make MongoDB the best agentic data layer. This page explains **why** each capability matters for agent memory and **how** ClawMongo implements it.
+ClawMongo uses 26 MongoDB capabilities that together make MongoDB the best agentic data layer. This page explains **why** each capability matters for agent memory and **how** ClawMongo implements it.
 
 ---
 
@@ -294,7 +294,7 @@ Events are append-only for the canonical fields. The `projectedAt` and `consolid
 
 Agent memory is written by both application code and LLM-generated tool calls. LLMs produce unpredictable output. Without schema validation, a malformed memory write silently corrupts the database. With it, the write fails fast and the application can handle the error.
 
-ClawMongo applies JSON Schema validation (`$jsonSchema`) to 17 collections with `validationAction: "error"`, so invalid documents are rejected at write time rather than silently accepted.
+ClawMongo applies JSON Schema validation (`$jsonSchema`) to 19 collections with `validationAction: "error"`, so invalid documents are rejected at write time rather than silently accepted.
 
 ### How It Works
 
@@ -323,7 +323,7 @@ Schema validation catches common LLM mistakes: missing required fields, wrong ty
 
 ### Collections Using This
 
-All 17 validated collections: `chunks`, `knowledge_base`, `kb_chunks`, `structured_mem`, `structured_mem_revisions`, `procedures`, `procedure_revisions`, `relevance_runs`, `relevance_artifacts`, `relevance_regressions`, `events`, `entities`, `relations`, `entity_links`, `episodes`, `ingest_runs`, `projection_runs`.
+All 19 validated collections: `chunks`, `knowledge_base`, `kb_chunks`, `structured_mem`, `structured_mem_revisions`, `procedures`, `procedure_revisions`, `relevance_runs`, `relevance_artifacts`, `relevance_regressions`, `events`, `entities`, `relations`, `entity_links`, `episodes`, `ingest_runs`, `projection_runs`, `query_cache`, `memory_mutations`.
 
 ---
 
@@ -426,7 +426,7 @@ The `VALID_SCOPES` and `VALID_ROLES` ReadonlySet patterns validate scope and rol
 
 ### Collections Using This
 
-All 20 collections use `agentId`-prefixed indexes. The `scope` and `scopeRef` fields add a second level of isolation within each agent (session, user, workspace, tenant, global).
+All 23 collections use `agentId`-prefixed indexes. The `scope` and `scopeRef` fields add a second level of isolation within each agent (session, user, workspace, tenant, global).
 
 ---
 
@@ -521,9 +521,233 @@ The CLI surface (`memory relevance *`) exposes this data for operators. Sampling
 
 ---
 
+## 13. Semantic Query Cache
+
+### Why This Matters
+
+Identical or near-identical queries should not re-execute the full retrieval pipeline. The semantic cache provides two tiers: SHA-256 exact match (sub-millisecond) and cosine similarity >= 0.95 (catches paraphrases). Cache hits skip search, reranking, and fusion entirely.
+
+### How It Works
+
+`checkCache()` runs before `searchV2()`. On miss, results are written back via fire-and-forget `writeCache()` with per-source TTL (conversation: 300s, KB: 3600s). Hit counts and timestamps tracked for observability.
+
+### Collections Using This
+
+- `query_cache` (SHA-256 hash index + vector search index + TTL index)
+
+---
+
+## 14. Time Series Telemetry
+
+### Why This Matters
+
+Every memory operation (search, entity extraction, rerank, profile synthesis, cache check) emits a telemetry document. Time series collections provide columnar storage, automatic bucketing, and server-side percentile computation (`$percentile`) for P50/P95/P99 latency dashboards.
+
+### How It Works
+
+`emitTelemetry()` is fire-and-forget. `getLatencyStats()` uses `$percentile` with `method: "approximate"`. `getOperationDistribution()` and `getCacheHitRate()` provide operational dashboards.
+
+### Collections Using This
+
+- `memory_telemetry` (time series, 7-day TTL, `granularity: "seconds"`)
+
+---
+
+## 15. Profile Synthesis
+
+### Why This Matters
+
+A single API call generates a comprehensive agent profile from structured memory (preferences, decisions, facts), top entities ranked by relation count, recent episodes, and activity patterns (event counts, role distribution, last active). This is the "who is this user" answer for long-running agents.
+
+### How It Works
+
+`synthesizeProfile()` runs parallel queries across 5 collections using `$facet` for structured memory grouping, `$lookup` for entity enrichment, and `$group` for activity pattern computation. Returns in ~5-50ms.
+
+### Collections Using This
+
+- `structured_mem`, `entities`, `relations`, `episodes`, `events`
+
+---
+
+## 16. Cross-Encoder Re-ranking
+
+### Why This Matters
+
+First-stage retrieval (vector + lexical) optimizes for recall. Cross-encoder re-ranking via Voyage rerank-2.5 optimizes for precision -- 8-11% accuracy improvement with instruction-following support. ON by default with 2-second timeout and graceful fallback to heuristic ranking.
+
+### How It Works
+
+`crossEncoderRerank()` sends query + document pairs to Voyage API. Three-bucket split: above minScore, overflow, below threshold. Empty snippets filtered before API call. `AbortSignal.timeout(2_000)` ensures chat-friendly latency.
+
+### Collections Using This
+
+- Operates on search results (no dedicated collection)
+
+---
+
+## 17. Query Rewriting
+
+### Why This Matters
+
+Terse queries ("auth config") miss relevant results. Synonym expansion ("auth" -> "authentication, login, oauth") and abbreviation expansion ("ts" -> "TypeScript") improve vector search recall without LLM calls.
+
+### How It Works
+
+`rewriteQuery()` applies deterministic synonym + abbreviation maps with a 3x expansion cap. Planner sees the original query; only the embedding stage sees the expanded version.
+
+### Collections Using This
+
+- Operates on queries (no dedicated collection)
+
+---
+
+## 18. Pluggable Entity Extraction
+
+### Why This Matters
+
+Knowledge graphs are only as good as their entity extraction. ClawMongo provides `RegexEntityExtractor` (fast, deterministic: @mentions, #tags, URLs, quoted names, dates) with an `LLMEntityExtractor` upgrade path (richer type classification, relationship inference). Both implement the `EntityExtractor` interface.
+
+### How It Works
+
+`extractAndUpsertEntities()` accepts a `role` parameter for role-based prompt selection. Entities are upserted via `bulkWrite` with `$setOnInsert` for creation-time fields. Relations capped at C(6,2)=15 per extraction.
+
+### Collections Using This
+
+- `entities`, `relations`, `entity_links`
+
+---
+
+## 19. Mutation Audit Trail
+
+### Why This Matters
+
+When memory is wrong, you need to know why. Every structured memory, entity, and relation write produces an audit record with before/after snapshots, operation type (create/update/delete), changed fields, and actor role. 90-day TTL auto-cleanup prevents unbounded growth.
+
+### How It Works
+
+`recordMutation()` is called fire-and-forget (via `Promise.allSettled`) after every write in `writeStructuredMemory`, `upsertEntity`, `upsertRelation`, and `deleteEntityConservative`. `getMutationHistory()` queries with agentId, collectionName, documentId, limit, and since filters.
+
+### Collections Using This
+
+- `memory_mutations` (compound query index + TTL 90-day index + per-document history index)
+
+---
+
+## 20. Status Lifecycle
+
+### Why This Matters
+
+Not all memories are equal. Archived episodes remain queryable for historical context but don't clutter active search. Deleted records are soft-deleted -- tombstoned, not removed -- preserving audit trails while excluding from retrieval.
+
+### How It Works
+
+Episodes and chunks get an optional `status` field: `active | archived | deleted`. All retrieval queries add `{ status: { $ne: "deleted" } }` which is backward compatible -- documents without the field match (MongoDB `$ne` semantics). `updateEpisodeStatus()` transitions episodes between states. `materializeEpisode()` sets `status: "active"` via `$setOnInsert`.
+
+### Collections Using This
+
+- `episodes`, `chunks` (7 query paths updated)
+
+---
+
+## 21. Procedural Memory Evolution
+
+### Why This Matters
+
+Agents that track workflow success rates improve over time. Procedures store version history, success/fail counts with timestamps, and bounded evolution history. When a procedure fails, you can trace what changed and when.
+
+### How It Works
+
+`recordProcedureOutcome()` uses atomic `$inc` for counters and `$set` for timestamps. `evolveProcedure()` bumps version, updates steps, and appends to evolution history using `$push` + `$slice: -20` for bounded arrays. `writeProcedure()` initializes defaults via `$setOnInsert` (version: 1, successCount: 0, failCount: 0, evolutionHistory: []).
+
+### Collections Using This
+
+- `procedures`
+
+---
+
+## 22. Conservative Graph Deletion
+
+### Why This Matters
+
+Accidental deletion of well-connected entities destroys knowledge graph integrity. Conservative deletion checks relation count before deleting -- if relations exist, it returns `conflictDetected: true` instead of deleting. A `force: true` override is available for intentional cleanup.
+
+### How It Works
+
+`deleteEntityConservative()` queries `relations` for `{ $or: [{ fromEntityId }, { toEntityId }] }` count. If > 0 and `force` is not set, returns without deleting. On deletion, records audit via `recordMutation` with the entity snapshot as `oldValue`.
+
+### Collections Using This
+
+- `entities`, `relations`, `memory_mutations`
+
+---
+
+## 23. Working Memory Bounds
+
+### Why This Matters
+
+Long sessions accumulate thousands of events. Without bounds, context injection blows the LLM token window. Working memory bounds return only the N most recent events, leveraging MongoDB's `$sort` + `$limit` optimization (the optimizer coalesces adjacent stages for top-N efficiency).
+
+### How It Works
+
+`getSessionEventsWithBound()` queries with `.sort({ timestamp: -1 }).limit(bound)` then reverses for chronological order. Default bound is 50, minimum clamped to 1 via `Math.max(1, bound)`. Uses existing compound index `{ agentId: 1, timestamp: -1 }`.
+
+### Collections Using This
+
+- `events`
+
+---
+
+## 24. Temporal Grounding
+
+### Why This Matters
+
+"Met with Sarah on May 7" is more useful than "Met with Sarah" -- dates anchor memories in time. Temporal grounding extracts dates from conversation text as first-class concept entities with `extractedAt` timestamps.
+
+### How It Works
+
+`RegexEntityExtractor` includes `DATE_REGEX` matching ISO dates (2023-05-07), natural dates (May 7, 2023), and US dates (5/7/2023). Extracted as type "concept" with confidence 0.7. `LLMEntityExtractor` prompt includes temporal grounding instruction. Entity upsert sets `extractedAt` via `$setOnInsert`.
+
+### Collections Using This
+
+- `entities`
+
+---
+
+## 25. Role-Based Extraction
+
+### Why This Matters
+
+"I prefer Python" from a user means something different than "I used Python" from an assistant. Role-based extraction uses different prompts -- user prompts focus on preferences, goals, and relationships; assistant prompts focus on capabilities, tools, and approaches. Prevents the LLM from hallucinating user preferences from assistant responses.
+
+### How It Works
+
+`LLMEntityExtractor.extract()` checks `context.role`: `"assistant"` -> `buildAssistantExtractionPrompt()`, everything else -> `buildUserExtractionPrompt()`. Entities get a `sourceRole` field ("user" | "assistant") tracked in the schema. `extractAndUpsertEntities()` accepts an optional `role` parameter.
+
+### Collections Using This
+
+- `entities`
+
+---
+
+## 26. Tiered Retrieval
+
+### Why This Matters
+
+Returning full document content for every search hit wastes tokens. In large memory spaces (1000+ episodes), this can consume the entire context window. Tiered retrieval returns IDs + scores first (~50-100 tokens), then fetches full content only for the top results on demand.
+
+### How It Works
+
+`searchV2` accepts `projection: "ids-only"` in search options. When set, result snippets are empty strings -- only `_id` and `score` are populated. `getEpisodesByIds()` fetches full content for selected episode IDs. Default behavior (`projection: "full"`) is unchanged.
+
+### Collections Using This
+
+- `episodes`, `chunks` (via `$project` after `$vectorSearch`)
+
+---
+
 ## The Full Picture
 
-All 12 capabilities work together in a single query/write cycle:
+All 26 capabilities work together in a single query/write cycle:
 
 ```text
 Write path:
@@ -532,20 +756,33 @@ Write path:
     -> Event-Sourcing writes canonical event               [6]
     -> Idempotent Upsert prevents duplicate writes         [11]
     -> Automated Embeddings index the text                 [1]
-    -> Entity extraction builds Knowledge Graph            [5]
+    -> Entity extraction (role-based prompts)              [18,25]
+       -> Temporal grounding captures dates                [24]
+       -> Knowledge Graph built from entities              [5]
+    -> Mutation Audit Trail tracks before/after            [19]
     -> Episode triggers consolidate event windows          [6]
+       -> Status Lifecycle assigns active state            [20]
     -> Multi-Tenant Isolation scopes everything by agent   [10]
     -> Change Streams notify other gateway instances       [8]
 
 Read path:
   query arrives
-    -> Retrieval planner selects paths
+    -> Semantic Query Cache: HIT? return cached            [13]
+    -> MISS: Query Rewriting expands synonyms              [17]
+    -> Retrieval planner selects from 8 paths
     -> Vector Search finds semantically similar content    [2]
     -> Full-Text Search finds exact keyword matches        [3]
     -> Hybrid Search fuses both result sets                [4]
     -> Knowledge Graph traverses entity relationships      [5]
-    -> Relevance Telemetry records what happened           [12]
+    -> Working Memory Bounds cap session context           [23]
+    -> Procedural Memory returns versioned workflows       [21]
+    -> Status Lifecycle excludes deleted records           [20]
+    -> Tiered Retrieval: IDs-only or full content          [26]
+    -> Cross-Encoder Re-ranking (Voyage rerank-2.5)        [16]
+    -> Profile Synthesis aggregates across 5 collections   [15]
+    -> Time Series Telemetry records what happened         [14]
+    -> Relevance Telemetry measures quality                [12]
     -> TTL Indexes keep caches and telemetry bounded       [9]
 ```
 
-This is why MongoDB is the best agentic data layer: one database, one operational surface, 12 capabilities that would otherwise require 5-6 separate services.
+This is why MongoDB is the best agentic data layer: one database, one operational surface, 26 capabilities that would otherwise require 5-6 separate services.

package/docs/reference/templates/AGENTS.md

@@ -20,7 +20,6 @@ Before doing anything else:
 1. Read `SOUL.md` — this is who you are
 2. Read `USER.md` — this is who you're helping
 3. Use `memory_search` for recent runtime context before answering questions about prior work, decisions, dates, people, preferences, or todos
-4. **If in MAIN SESSION** (direct chat with your human): Read `MEMORY.md` only as bridge guidance when it is relevant
 
 Don't ask permission. Just do it.
 
@@ -30,20 +29,16 @@ You wake up fresh each session. Continuity comes from both MongoDB memory and a
 small set of human-authored workspace files:
 
 - **Daily bridge notes:** `memory/YYYY-MM-DD.md` (create `memory/` if needed) — optional human-authored raw notes
-- **Bridge guidance:** `MEMORY.md` — curated human-authored notes for the main/private session
-- **Runtime durable memory:** use `memory_write` when available; MongoDB is the canonical runtime memory store
+- **Runtime durable memory:** use `memory_write` when available; MongoDB is the sole runtime memory store
 
 Capture what matters in the right place. Instructions and policy live in
 Markdown. Durable runtime facts and decisions live in MongoDB.
 
-### 🧠 MEMORY.md - Your Bridge Notes
+### Runtime Memory
 
-- **ONLY load in main session** (direct chats with your human)
-- **DO NOT load in shared contexts** (Discord, group chats, sessions with other people)
-- This is for **security** — contains personal context that shouldn't leak to strangers
-- Treat `MEMORY.md` as human-authored bridge guidance, not the canonical runtime memory store
+- MongoDB is the sole runtime memory store
 - Prefer `memory_write` for durable runtime facts, decisions, preferences, todos, people, projects, and architecture notes
-- Touch `MEMORY.md` only when you are intentionally maintaining bridge guidance, not as a default memory sink
+- Do not use workspace files as a memory store
 
 ### 📝 Write It Down - No "Mental Notes"!
 
@@ -216,7 +211,7 @@ Weekly promotion cycle:
 
 - **Daily notes** (`memory/YYYY-MM-DD.md`) are raw capture -- ephemeral by nature
 - **Structured memory** (MongoDB via `memory_write`) is durable -- survives compaction and session resets
-- **MEMORY.md** remains human-authored bridge guidance only -- do not treat it as a memory store
+- **MongoDB** is the sole runtime memory store -- do not use workspace files as a memory store
 
 The goal: important facts graduate from daily notes to MongoDB structured memory within a week. Bridge notes stay small. MongoDB stays canonical.
 

package/docs/research/2026-03-22-atlas-local-preview-web.md

@@ -1,11 +1,13 @@
 # Web Research: MongoDB Atlas Local (Preview) — mongod + mongot bundled Docker image
 
 ## Execution
+
 - Preferred backend: websearch+webfetch
 - Allowed fallbacks: websearch-only, webfetch-only
 - Research round: 1 (understanding Atlas Local and why it supersedes separate mongod + mongot)
 
 ## Sources Used
+
 - WebFetch on `raw.githubusercontent.com/mongodb/docs-atlas-cli/master/source/atlas-cli-deploy-docker.txt` — official Atlas CLI Docker deployment docs (verbatim RST source)
 - WebFetch on `raw.githubusercontent.com/mongodb/docs-atlas-cli/master/source/atlas-cli-deploy-local.txt` — official Atlas CLI local deployment docs (verbatim RST source)
 - WebFetch on `raw.githubusercontent.com/mongodb/docs-atlas-cli/master/source/atlas-cli-deploy-fts.txt` — Atlas CLI FTS + AVS docs
@@ -16,6 +18,7 @@
 **Bright Data:** Not available; fell back to WebFetch + curl for raw sources.
 
 ## Research Quality
+
 - Status: COMPLETE
 - Quality level: high
 - Backend mode: websearch+webfetch
@@ -38,13 +41,13 @@ mongodb/mongodb-atlas-local
 
 Confirmed from the Docker Hub API (as of 2026-03-20, the latest rebuild date):
 
-| Tag pattern | Purpose |
-|---|---|
-| `latest` | Current stable release (maps to latest MongoDB 8.x + mongot) |
-| `8.2`, `8.2.6`, `8.2.6-20260320T081259Z` | Stable MongoDB 8.2.x + mongot |
-| `8.0`, `8.0.20`, etc. | Stable MongoDB 8.0.x + mongot |
-| `7.0`, `7.0.31`, etc. | Stable MongoDB 7.0.x + mongot |
-| `preview` | **Pre-release channel** — currently tracks MongoDB 8.2 + mongot with auto-embedding (Voyage AI) enabled. Separate from `latest`; ~70 MB smaller per arch than `latest` as of 2026-03-20 |
+| Tag pattern                              | Purpose                                                                                                                                                                                 |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `latest`                                 | Current stable release (maps to latest MongoDB 8.x + mongot)                                                                                                                            |
+| `8.2`, `8.2.6`, `8.2.6-20260320T081259Z` | Stable MongoDB 8.2.x + mongot                                                                                                                                                           |
+| `8.0`, `8.0.20`, etc.                    | Stable MongoDB 8.0.x + mongot                                                                                                                                                           |
+| `7.0`, `7.0.31`, etc.                    | Stable MongoDB 7.0.x + mongot                                                                                                                                                           |
+| `preview`                                | **Pre-release channel** — currently tracks MongoDB 8.2 + mongot with auto-embedding (Voyage AI) enabled. Separate from `latest`; ~70 MB smaller per arch than `latest` as of 2026-03-20 |
 
 The `preview` digest as of 2026-03-20: `sha256:4f4c43e8711ce31660b931bd96e76e679b311702a0cc49e03c926615aaf4c868`
 
@@ -73,6 +76,7 @@ Both support `linux/amd64` and `linux/arm64`.
 ### Before Atlas Local
 
 Running Atlas Search + Vector Search locally required:
+
 1. Install MongoDB Community or Enterprise Edition (`mongod`)
 2. Separately download, install, and configure `mongot` (the search process)
 3. Configure `mongot` to bind to `mongod` via keyfile / keyfile path
@@ -83,11 +87,13 @@ Running Atlas Search + Vector Search locally required:
 ### With Atlas Local
 
 Single command replaces all of the above:
+
 ```sh
 docker run -p 27017:27017 mongodb/mongodb-atlas-local
 ```
 
 Or with Docker Compose:
+
 ```yaml
 services:
   mongodb:
@@ -106,6 +112,7 @@ volumes:
 ```
 
 Key advantages:
+
 - **Single container, single pull** — one image contains everything
 - **Correct startup sequencing** — the entrypoint ensures mongot starts in the right order relative to mongod; do not override the `command` in Docker Compose or it breaks this
 - **Built-in health check** — poll `docker inspect .State.Health.Status` to know when to connect; no custom scripts needed
@@ -123,6 +130,7 @@ Key advantages:
 "Automated Embedding" is a Preview feature available in MongoDB Community Edition **v8.2 and later**, delivered via the `preview` Docker tag.
 
 Official statement from the docs:
+
 > "Automated embedding is available as a Preview feature only for MongoDB Community Edition v8.2 and later. The feature and the corresponding documentation might change at any time during the Preview period."
 
 ### How It Works
@@ -155,29 +163,30 @@ The generated embeddings are stored in a **separate system collection** on the s
 ```js
 db.collection.aggregate([
   {
-    "$vectorSearch": {
-      "index": "myVectorIndex",
-      "path": "summary",
-      "query": { "text": "properties near amusement parks" },
-      "numCandidates": 100,
-      "limit": 10
-    }
-  }
-])
+    $vectorSearch: {
+      index: "myVectorIndex",
+      path: "summary",
+      query: { text: "properties near amusement parks" },
+      numCandidates: 100,
+      limit: 10,
+    },
+  },
+]);
 ```
 
 ### Supported Voyage AI Embedding Models
 
-| Model | Use Case |
-|---|---|
-| `voyage-4-lite` | High-volume, cost-sensitive applications |
-| `voyage-4` (recommended) | General text search, balanced performance |
-| `voyage-4-large` | Maximum accuracy for complex semantic relationships |
-| `voyage-code-3` | Code search and technical documentation |
+| Model                    | Use Case                                            |
+| ------------------------ | --------------------------------------------------- |
+| `voyage-4-lite`          | High-volume, cost-sensitive applications            |
+| `voyage-4` (recommended) | General text search, balanced performance           |
+| `voyage-4-large`         | Maximum accuracy for complex semantic relationships |
+| `voyage-code-3`          | Code search and technical documentation             |
 
 ### API Key Recommendation
 
 MongoDB recommends two separate Voyage AI API keys:
+
 - One for **indexing operations** (higher throughput, tolerant of delays)
 - One for **query operations** (low-latency, user-facing)
 
@@ -186,6 +195,7 @@ Keys can be generated via Atlas UI (which also provides monitoring + rate limiti
 ### Why This Matters for ClawMongo
 
 ClawMongo v2 currently calls the Voyage AI API externally from application code (via the `mongodb-search.ts` / hybrid pipeline). With auto-embedding in the `preview` image:
+
 - No application code needed to call Voyage AI at index time or query time
 - mongot handles embedding generation and sync automatically
 - `$vectorSearch` queries can use plain text (`query.text`) instead of pre-computed vectors
@@ -222,15 +232,15 @@ From the official auto-embedding docs (as of 2026-03-22):
 
 ## 7. Comparison: mongod Standalone vs Atlas Local vs Preview
 
-| Aspect | `mongo:8.0` (raw mongod) | `mongodb/mongodb-atlas-local` (stable) | `mongodb/mongodb-atlas-local:preview` |
-|---|---|---|---|
-| Atlas Search ($search) | No | Yes | Yes |
-| Atlas Vector Search ($vectorSearch) | No | Yes | Yes |
-| Auto-embeddings (Voyage AI) | No | No | Yes (Preview) |
-| Built-in health check | No | Yes | Yes |
-| Single container | Yes | Yes | Yes |
-| Production-safe | Yes | Dev/test only | No (Preview) |
-| Min MongoDB version | Any | 7.0+ | 8.2+ |
+| Aspect                              | `mongo:8.0` (raw mongod) | `mongodb/mongodb-atlas-local` (stable) | `mongodb/mongodb-atlas-local:preview` |
+| ----------------------------------- | ------------------------ | -------------------------------------- | ------------------------------------- |
+| Atlas Search ($search)              | No                       | Yes                                    | Yes                                   |
+| Atlas Vector Search ($vectorSearch) | No                       | Yes                                    | Yes                                   |
+| Auto-embeddings (Voyage AI)         | No                       | No                                     | Yes (Preview)                         |
+| Built-in health check               | No                       | Yes                                    | Yes                                   |
+| Single container                    | Yes                      | Yes                                    | Yes                                   |
+| Production-safe                     | Yes                      | Dev/test only                          | No (Preview)                          |
+| Min MongoDB version                 | Any                      | 7.0+                                   | 8.2+                                  |
 
 ---