memorymaster 3.12.0__tar.gz → 3.14.0__tar.gz

{memorymaster-3.12.0/memorymaster.egg-info → memorymaster-3.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.12.0
+Version: 3.14.0
 Summary: Production-grade memory reliability system for AI coding agents. Lifecycle-managed claims with citations, conflict detection, steward governance, and MCP integration.
 Author: wolverin0
 License: MIT
@@ -50,9 +50,9 @@ Lifecycle-managed claims with citations, conflict detection, steward governance,
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-1029-green.svg)]()
-[![MCP Tools](https://img.shields.io/badge/MCP%20tools-22-purple.svg)]()
-[![CLI Commands](https://img.shields.io/badge/CLI%20commands-64-orange.svg)]()
+[![Tests](https://img.shields.io/badge/tests-1953-green.svg)]()
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-24-purple.svg)]()
+[![CLI Commands](https://img.shields.io/badge/CLI%20commands-86-orange.svg)]()
 [![PyPI](https://img.shields.io/pypi/v/memorymaster.svg)](https://pypi.org/project/memorymaster/)
 
 MemoryMaster prevents the #1 problem with agent memory: **drift, stale assumptions, and unsafe disclosure**. It gives Claude Code, Codex, and any MCP-compatible agent persistent, verifiable memory with a full claim lifecycle, citation tracking, conflict detection, and human-in-the-loop governance.
@@ -61,29 +61,23 @@ MemoryMaster prevents the #1 problem with agent memory: **drift, stale assumptio
 
 ## Architecture
 
+MemoryMaster is layered around MCP/CLI entry points, the `MemoryService` facade, SQLite/Postgres
+storage, optional Qdrant vector search, scheduled jobs, and the Obsidian wiki/vault layer. The
+canonical ingest path is:
+
+```text
+MCP/CLI -> sensitivity filter -> MemoryService.ingest -> store write -> FTS5 index
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Agent Runtime                            │
-│  (Claude Code / Codex / any MCP-compatible agent)               │
-└────────────┬────────────────────────────────┬───────────────────┘
-             │ MCP (22 tools)                 │ CLI (64 commands)
-             v                                v
-┌─────────────────────────────────────────────────────────────────┐
-│                      MemoryMaster Core                          │
-│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
-│  │ Ingestor │  │ Extractor │  │ Validator │  │ State Engine  │  │
-│  │ (events) │->│ (claims)  │->│ (probes)  │->│ (6-state FSM) │  │
-│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
-│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
-│  │ Retrieval│  │ Compactor │  │ Steward  │  │  Dashboard    │  │
-│  │ (hybrid) │  │ (archive) │  │ (govern) │  │  (HTML+SSE)   │  │
-│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
-└────────┬──────────────┬──────────────┬──────────┬───────────────┘
-         v              v              v          v
-   SQLite/Postgres   Qdrant      Ollama/CLI    Claude Code
-                    (vectors)   (LLM stack)   Auto Dream + Vault
+
+The query path is:
+
+```text
+query_memory -> MemoryService.query -> storage reads + optional Qdrant candidates -> ranked context
 ```
 
+See [docs/architecture.md](docs/architecture.md) for the current module map, data-flow details,
+recent PR status, and sensitivity-filter invariants.
+
 ## Key features
 
 - **6-state lifecycle**: `candidate` → `confirmed` → `stale` → `superseded` → `conflicted` → `archived`
@@ -94,7 +88,8 @@ MemoryMaster prevents the #1 problem with agent memory: **drift, stale assumptio
 - **Steward governance**: multi-probe validators (filesystem, format, citation, semantic, tool) with proposal review
 - **Conflict resolution**: 5-tier auto (confidence > freshness > citations > LLM > manual)
 - **Auto-redaction** at ingest: JWT, GitHub tokens, Bearer, AWS keys, SSH keys, custom patterns
-- **LLM Wiki**: compiled-truth + append-only timeline articles with progressive-disclosure frontmatter
+- **LLM Wiki**: compiled-truth + append-only timeline articles with progressive-disclosure frontmatter, `explored: true|false` operator-review marker, and inline `> [!contradiction]` Obsidian callouts
+- **Atlas Inbox V1** (new in v3.13.0): WhatsApp ingestion → source/evidence/action proposal lifecycle → Super-Productivity export. Versioned API/CLI contract for downstream consumers (LifeAgent, etc.) — see [`docs/atlas-api-contract-v1.md`](docs/atlas-api-contract-v1.md). Real provider adapters (`OpenAIWhisperTranscriptionProvider`, `TesseractOcrProvider`) behind `Protocol`s; mock providers stay default.
 - **Dual backend**: SQLite (zero-config) and Postgres (full feature parity with pgvector)
 - **Dream Bridge** for bidirectional sync with Claude Code's Auto Dream
 - **7-hook stack**: recall, classify, validate-wiki, session-start, auto-ingest, precompact, steward-cron
@@ -103,18 +98,20 @@ Full feature index lives in [`docs/handbook.md`](docs/handbook.md).
 
 ## Prerequisites
 
-**Required**
+**Required (the package won't function without these)**
 
 - Python **3.10+** with `pip`
 - Claude Code, Codex, or any MCP-compatible agent
+- **An LLM provider** — pick one: Claude Code OAuth (free if you're a subscriber, set `MEMORYMASTER_LLM_PROVIDER=claude_cli`), a free Gemini API key from [aistudio.google.com](https://aistudio.google.com), OpenAI, Anthropic API, or local Ollama. The steward, auto-ingest, and wiki-absorb cycles all need an LLM — without one, claims pile up as `candidate` and never get validated, deduped, or compiled into the wiki.
+
+**Strongly recommended (you'll lose ~80% of the value without these)**
+
+- **Node.js 18+** for [graphify](https://github.com/wolverin0/graphify) and [GitNexus](https://github.com/wolverin0/gitnexus) — these are the cached intelligence layers that make MemoryMaster cheap to query. Without them, every "what does this codebase do?" question burns tokens cold-exploring files the graph already mapped. The `intelligence-first` workflow in `CLAUDE.md` assumes both are installed.
+- **Obsidian 1.6+** with the [Bases](https://help.obsidian.md/Plugins/Bases) core plugin — the wiki engine writes plain Markdown so any editor works, but Obsidian's backlinks, graph view, and Bases dashboards are how you actually navigate `wiki-absorb` output. Without Obsidian, the wiki is just a folder of files.
 
-**Optional**
+**Optional (nice to have)**
 
-- **Already a Claude Code subscriber?** No API key needed — set `MEMORYMASTER_LLM_PROVIDER=claude_cli` and the steward + auto-ingest hooks will use your existing OAuth via the local `claude --print` binary
-- A free Gemini API key from [aistudio.google.com](https://aistudio.google.com) — powers the auto-ingest hook at ~zero cost
-- **Node.js 18+** for graphify and GitNexus
-- **Obsidian 1.6+** with the Bases core plugin (for visual wiki browsing)
-- **Docker** for Qdrant (SQLite FTS5 is the default and works out of the box)
+- **Docker** for Qdrant — vector retrieval. SQLite FTS5 is the default and works out of the box; add Qdrant when you want semantic recall on top of keyword search.
 
 ## Quick start
 

{memorymaster-3.12.0 → memorymaster-3.14.0}/README.md

@@ -6,9 +6,9 @@ Lifecycle-managed claims with citations, conflict detection, steward governance,
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-1029-green.svg)]()
-[![MCP Tools](https://img.shields.io/badge/MCP%20tools-22-purple.svg)]()
-[![CLI Commands](https://img.shields.io/badge/CLI%20commands-64-orange.svg)]()
+[![Tests](https://img.shields.io/badge/tests-1953-green.svg)]()
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-24-purple.svg)]()
+[![CLI Commands](https://img.shields.io/badge/CLI%20commands-86-orange.svg)]()
 [![PyPI](https://img.shields.io/pypi/v/memorymaster.svg)](https://pypi.org/project/memorymaster/)
 
 MemoryMaster prevents the #1 problem with agent memory: **drift, stale assumptions, and unsafe disclosure**. It gives Claude Code, Codex, and any MCP-compatible agent persistent, verifiable memory with a full claim lifecycle, citation tracking, conflict detection, and human-in-the-loop governance.
@@ -17,29 +17,23 @@ MemoryMaster prevents the #1 problem with agent memory: **drift, stale assumptio
 
 ## Architecture
 
+MemoryMaster is layered around MCP/CLI entry points, the `MemoryService` facade, SQLite/Postgres
+storage, optional Qdrant vector search, scheduled jobs, and the Obsidian wiki/vault layer. The
+canonical ingest path is:
+
+```text
+MCP/CLI -> sensitivity filter -> MemoryService.ingest -> store write -> FTS5 index
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Agent Runtime                            │
-│  (Claude Code / Codex / any MCP-compatible agent)               │
-└────────────┬────────────────────────────────┬───────────────────┘
-             │ MCP (22 tools)                 │ CLI (64 commands)
-             v                                v
-┌─────────────────────────────────────────────────────────────────┐
-│                      MemoryMaster Core                          │
-│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
-│  │ Ingestor │  │ Extractor │  │ Validator │  │ State Engine  │  │
-│  │ (events) │->│ (claims)  │->│ (probes)  │->│ (6-state FSM) │  │
-│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
-│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
-│  │ Retrieval│  │ Compactor │  │ Steward  │  │  Dashboard    │  │
-│  │ (hybrid) │  │ (archive) │  │ (govern) │  │  (HTML+SSE)   │  │
-│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
-└────────┬──────────────┬──────────────┬──────────┬───────────────┘
-         v              v              v          v
-   SQLite/Postgres   Qdrant      Ollama/CLI    Claude Code
-                    (vectors)   (LLM stack)   Auto Dream + Vault
+
+The query path is:
+
+```text
+query_memory -> MemoryService.query -> storage reads + optional Qdrant candidates -> ranked context
 ```
 
+See [docs/architecture.md](docs/architecture.md) for the current module map, data-flow details,
+recent PR status, and sensitivity-filter invariants.
+
 ## Key features
 
 - **6-state lifecycle**: `candidate` → `confirmed` → `stale` → `superseded` → `conflicted` → `archived`
@@ -50,7 +44,8 @@ MemoryMaster prevents the #1 problem with agent memory: **drift, stale assumptio
 - **Steward governance**: multi-probe validators (filesystem, format, citation, semantic, tool) with proposal review
 - **Conflict resolution**: 5-tier auto (confidence > freshness > citations > LLM > manual)
 - **Auto-redaction** at ingest: JWT, GitHub tokens, Bearer, AWS keys, SSH keys, custom patterns
-- **LLM Wiki**: compiled-truth + append-only timeline articles with progressive-disclosure frontmatter
+- **LLM Wiki**: compiled-truth + append-only timeline articles with progressive-disclosure frontmatter, `explored: true|false` operator-review marker, and inline `> [!contradiction]` Obsidian callouts
+- **Atlas Inbox V1** (new in v3.13.0): WhatsApp ingestion → source/evidence/action proposal lifecycle → Super-Productivity export. Versioned API/CLI contract for downstream consumers (LifeAgent, etc.) — see [`docs/atlas-api-contract-v1.md`](docs/atlas-api-contract-v1.md). Real provider adapters (`OpenAIWhisperTranscriptionProvider`, `TesseractOcrProvider`) behind `Protocol`s; mock providers stay default.
 - **Dual backend**: SQLite (zero-config) and Postgres (full feature parity with pgvector)
 - **Dream Bridge** for bidirectional sync with Claude Code's Auto Dream
 - **7-hook stack**: recall, classify, validate-wiki, session-start, auto-ingest, precompact, steward-cron
@@ -59,18 +54,20 @@ Full feature index lives in [`docs/handbook.md`](docs/handbook.md).
 
 ## Prerequisites
 
-**Required**
+**Required (the package won't function without these)**
 
 - Python **3.10+** with `pip`
 - Claude Code, Codex, or any MCP-compatible agent
+- **An LLM provider** — pick one: Claude Code OAuth (free if you're a subscriber, set `MEMORYMASTER_LLM_PROVIDER=claude_cli`), a free Gemini API key from [aistudio.google.com](https://aistudio.google.com), OpenAI, Anthropic API, or local Ollama. The steward, auto-ingest, and wiki-absorb cycles all need an LLM — without one, claims pile up as `candidate` and never get validated, deduped, or compiled into the wiki.
+
+**Strongly recommended (you'll lose ~80% of the value without these)**
+
+- **Node.js 18+** for [graphify](https://github.com/wolverin0/graphify) and [GitNexus](https://github.com/wolverin0/gitnexus) — these are the cached intelligence layers that make MemoryMaster cheap to query. Without them, every "what does this codebase do?" question burns tokens cold-exploring files the graph already mapped. The `intelligence-first` workflow in `CLAUDE.md` assumes both are installed.
+- **Obsidian 1.6+** with the [Bases](https://help.obsidian.md/Plugins/Bases) core plugin — the wiki engine writes plain Markdown so any editor works, but Obsidian's backlinks, graph view, and Bases dashboards are how you actually navigate `wiki-absorb` output. Without Obsidian, the wiki is just a folder of files.
 
-**Optional**
+**Optional (nice to have)**
 
-- **Already a Claude Code subscriber?** No API key needed — set `MEMORYMASTER_LLM_PROVIDER=claude_cli` and the steward + auto-ingest hooks will use your existing OAuth via the local `claude --print` binary
-- A free Gemini API key from [aistudio.google.com](https://aistudio.google.com) — powers the auto-ingest hook at ~zero cost
-- **Node.js 18+** for graphify and GitNexus
-- **Obsidian 1.6+** with the Bases core plugin (for visual wiki browsing)
-- **Docker** for Qdrant (SQLite FTS5 is the default and works out of the box)
+- **Docker** for Qdrant — vector retrieval. SQLite FTS5 is the default and works out of the box; add Qdrant when you want semantic recall on top of keyword search.
 
 ## Quick start
 

{memorymaster-3.12.0 → memorymaster-3.14.0}/memorymaster/_storage_lifecycle.py

@@ -23,14 +23,14 @@ from memorymaster.models import (
     validate_transition_event_type,
 )
 
-logger = logging.getLogger(__name__)
-
 from memorymaster._storage_shared import (
     EVENT_HASH_ALGO,
     ConcurrentModificationError,
     utc_now,
 )
 
+logger = logging.getLogger(__name__)
+
 
 class _LifecycleMixin:
 
@@ -102,14 +102,64 @@ class _LifecycleMixin:
         old_claim = self.get_claim(old_claim_id, include_citations=False)
         if old_claim is None:
             return
-        self.apply_status_transition(
-            old_claim,
-            to_status="superseded",
-            reason=reason,
-            event_type="supersession",
-            replaced_by_claim_id=new_claim_id,
-        )
-        self.set_supersedes(new_claim_id, old_claim_id)
+        if old_claim.status == "superseded" or old_claim.replaced_by_claim_id is not None:
+            raise ConcurrentModificationError(
+                f"Claim {old_claim_id} was already superseded. Reload and retry."
+            )
+
+        now = utc_now()
+        with self.connect() as conn:
+            target = conn.execute(
+                "SELECT supersedes_claim_id FROM claims WHERE id = ?",
+                (new_claim_id,),
+            ).fetchone()
+            if target is None:
+                raise ValueError(f"Replacement claim {new_claim_id} does not exist.")
+            if target["supersedes_claim_id"] not in {None, old_claim_id}:
+                raise ConcurrentModificationError(
+                    f"Claim {new_claim_id} already supersedes another claim. Reload and retry."
+                )
+
+            cur = conn.execute(
+                """
+                UPDATE claims
+                SET status = 'superseded', updated_at = ?, replaced_by_claim_id = ?,
+                    version = version + 1, valid_until = COALESCE(?, valid_until)
+                WHERE id = ? AND version = ? AND status != 'superseded'
+                    AND replaced_by_claim_id IS NULL
+                """,
+                (now, new_claim_id, now, old_claim_id, old_claim.version),
+            )
+            if cur.rowcount == 0:
+                raise ConcurrentModificationError(
+                    f"Claim {old_claim_id} was modified by another writer. Reload and retry."
+                )
+
+            cur = conn.execute(
+                """
+                UPDATE claims
+                SET supersedes_claim_id = ?, updated_at = ?
+                WHERE id = ? AND (supersedes_claim_id IS NULL OR supersedes_claim_id = ?)
+                """,
+                (old_claim_id, now, new_claim_id, old_claim_id),
+            )
+            if cur.rowcount == 0:
+                conn.rollback()
+                raise ConcurrentModificationError(
+                    f"Claim {new_claim_id} was modified by another writer. Reload and retry."
+                )
+
+            self._insert_event_row(
+                conn,
+                claim_id=old_claim.id,
+                event_type="supersession",
+                from_status=old_claim.status,
+                to_status="superseded",
+                details=reason,
+                payload_json=json.dumps({"replaced_by_claim_id": new_claim_id}),
+                created_at=now,
+            )
+            conn.commit()
 
 
     def delete_old_events(self, retain_days: int) -> int:

{memorymaster-3.12.0 → memorymaster-3.14.0}/memorymaster/_storage_schema.py

@@ -52,6 +52,151 @@ class _SchemaMixin:
             "CREATE INDEX IF NOT EXISTS idx_embeddings_updated_at ON claim_embeddings(updated_at)"
         )
 
+    @staticmethod
+    def _ensure_atlas_source_schema(conn: sqlite3.Connection) -> None:
+        """Ensure Atlas Inbox external source/evidence/action proposal tables exist.
+
+        Critical ordering (forward-migration aware):
+          1. CREATE TABLE IF NOT EXISTS — idempotent on existing tables
+             but does NOT add new columns to pre-existing tables.
+          2. ALTER TABLE ADD COLUMN — forward-migrate columns added in
+             later versions (idempotent via duplicate-column catch).
+          3. CREATE INDEX IF NOT EXISTS — runs LAST, after columns are
+             guaranteed to exist on both fresh and stale DBs.
+
+        Bug history: in v1.5.0, the index-on-new-column statements were
+        in the same executescript as CREATE TABLE, which fired BEFORE
+        the ALTER. On a stale Atlas DB (pre-sensitivity), CREATE INDEX
+        ON source_items(sensitivity) failed with 'no such column'. v1.5.1
+        splits the script and runs ALTER between the table and index
+        phases. See PR #27 / claim mm-ce8b.
+        """
+        # Phase 1: tables (idempotent — IF NOT EXISTS)
+        conn.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS external_sources (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                source_type TEXT NOT NULL,
+                display_name TEXT NOT NULL,
+                config_json TEXT,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                UNIQUE (source_type, display_name)
+            );
+
+            CREATE TABLE IF NOT EXISTS source_items (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                source_id INTEGER NOT NULL,
+                source_item_id TEXT NOT NULL,
+                item_type TEXT NOT NULL,
+                chat_id TEXT,
+                sender_id TEXT,
+                sender_name TEXT,
+                occurred_at TEXT,
+                text TEXT,
+                payload_json TEXT,
+                content_hash TEXT,
+                sensitivity TEXT CHECK (sensitivity IS NULL OR sensitivity IN ('none','low','medium','high','redacted')),
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                FOREIGN KEY (source_id) REFERENCES external_sources(id) ON DELETE CASCADE,
+                UNIQUE (source_id, source_item_id)
+            );
+
+            CREATE TABLE IF NOT EXISTS evidence_items (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                source_item_id INTEGER NOT NULL,
+                evidence_type TEXT NOT NULL,
+                text TEXT,
+                media_path TEXT,
+                provider TEXT,
+                confidence REAL CHECK (confidence IS NULL OR (confidence >= 0.0 AND confidence <= 1.0)),
+                payload_json TEXT,
+                sensitivity TEXT CHECK (sensitivity IS NULL OR sensitivity IN ('none','low','medium','high','redacted')),
+                created_at TEXT NOT NULL,
+                FOREIGN KEY (source_item_id) REFERENCES source_items(id) ON DELETE CASCADE
+            );
+
+            CREATE TABLE IF NOT EXISTS action_proposals (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                proposal_type TEXT NOT NULL,
+                title TEXT NOT NULL,
+                description TEXT,
+                source_item_id INTEGER,
+                evidence_item_id INTEGER,
+                claim_id INTEGER,
+                suggested_due_at TEXT,
+                destination TEXT NOT NULL DEFAULT 'manual',
+                status TEXT NOT NULL DEFAULT 'candidate'
+                    CHECK (status IN ('candidate', 'approved', 'rejected', 'exported', 'failed')),
+                confidence REAL NOT NULL DEFAULT 0.5 CHECK (confidence >= 0.0 AND confidence <= 1.0),
+                payload_json TEXT,
+                exported_at TEXT,
+                external_ref TEXT,
+                idempotency_key TEXT,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                FOREIGN KEY (source_item_id) REFERENCES source_items(id) ON DELETE SET NULL,
+                FOREIGN KEY (evidence_item_id) REFERENCES evidence_items(id) ON DELETE SET NULL,
+                FOREIGN KEY (claim_id) REFERENCES claims(id) ON DELETE SET NULL
+            );
+
+            CREATE TABLE IF NOT EXISTS media_retry_queue (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                source_item_id INTEGER NOT NULL,
+                media_key TEXT NOT NULL,
+                chat_id TEXT,
+                media_type TEXT,
+                media_path TEXT,
+                media_url TEXT,
+                status TEXT NOT NULL DEFAULT 'pending'
+                    CHECK (status IN ('pending', 'retrying', 'expired', 'done', 'failed')),
+                attempt_count INTEGER NOT NULL DEFAULT 0,
+                last_http_status INTEGER,
+                last_error TEXT,
+                next_attempt_time TEXT,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                FOREIGN KEY (source_item_id) REFERENCES source_items(id) ON DELETE CASCADE,
+                UNIQUE (source_item_id, media_key)
+            );
+            """
+        )
+
+        # Phase 2: forward-migrate columns added in later versions.
+        # Pattern matches _ensure_claim_idempotency_schema. MUST run BEFORE
+        # any indexes that reference these columns (otherwise stale DBs
+        # fail with 'no such column').
+        for table in ("source_items", "evidence_items"):
+            try:
+                conn.execute(f"ALTER TABLE {table} ADD COLUMN sensitivity TEXT")
+            except sqlite3.OperationalError as exc:
+                if "duplicate column name" not in str(exc).lower():
+                    raise
+
+        # Phase 3: indexes (now safe — all columns guaranteed to exist).
+        conn.executescript(
+            """
+            CREATE INDEX IF NOT EXISTS idx_external_sources_type ON external_sources(source_type);
+            CREATE INDEX IF NOT EXISTS idx_source_items_source_id ON source_items(source_id);
+            CREATE INDEX IF NOT EXISTS idx_source_items_chat_id ON source_items(chat_id);
+            CREATE INDEX IF NOT EXISTS idx_source_items_occurred_at ON source_items(occurred_at);
+            CREATE INDEX IF NOT EXISTS idx_source_items_content_hash ON source_items(content_hash);
+            CREATE INDEX IF NOT EXISTS idx_evidence_items_source_item_id ON evidence_items(source_item_id);
+            CREATE INDEX IF NOT EXISTS idx_evidence_items_type ON evidence_items(evidence_type);
+            CREATE INDEX IF NOT EXISTS idx_action_proposals_status ON action_proposals(status);
+            CREATE INDEX IF NOT EXISTS idx_action_proposals_destination ON action_proposals(destination);
+            CREATE UNIQUE INDEX IF NOT EXISTS idx_action_proposals_idempotency_key
+                ON action_proposals(idempotency_key)
+                WHERE idempotency_key IS NOT NULL;
+            CREATE INDEX IF NOT EXISTS idx_source_items_sensitivity ON source_items(sensitivity);
+            CREATE INDEX IF NOT EXISTS idx_evidence_items_sensitivity ON evidence_items(sensitivity);
+            CREATE INDEX IF NOT EXISTS idx_media_retry_status ON media_retry_queue(status);
+            CREATE INDEX IF NOT EXISTS idx_media_retry_next_attempt ON media_retry_queue(next_attempt_time);
+            CREATE INDEX IF NOT EXISTS idx_media_retry_source_item ON media_retry_queue(source_item_id);
+            """
+        )
+
 
     @staticmethod
     def _ensure_claim_idempotency_schema(conn: sqlite3.Connection) -> None: