contextos-memory-runtime 1.0.0rc2__py3-none-any.whl

contextos/storage/database.py

@@ -0,0 +1,497 @@
+"""SQLite database management for ContextOS.
+
+Handles connection pooling, WAL mode, migrations, and schema setup.
+All database access goes through the Database class, which provides
+the connection to repositories.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from pathlib import Path
+
+import aiosqlite
+
+from contextos.core.exceptions import MigrationError
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Schema SQL — Phase 1 initial schema
+# ---------------------------------------------------------------------------
+
+SCHEMA_VERSION = 7
+
+SCHEMA_SQL = """
+-- Schema version tracking
+CREATE TABLE IF NOT EXISTS schema_version (
+    version INTEGER PRIMARY KEY,
+    applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+    description TEXT NOT NULL
+);
+
+-- Memories: the core data object
+CREATE TABLE IF NOT EXISTS memories (
+    id TEXT PRIMARY KEY,
+    content TEXT NOT NULL,
+    content_hash TEXT NOT NULL,
+    type TEXT NOT NULL DEFAULT 'context',
+    source_type TEXT NOT NULL DEFAULT 'cli_input',
+    source_uri TEXT,
+    provenance_event_id TEXT,
+    status TEXT NOT NULL DEFAULT 'candidate',
+    confidence REAL NOT NULL DEFAULT 0.8,
+    importance REAL NOT NULL DEFAULT 0.5,
+    privacy_level TEXT NOT NULL DEFAULT 'personal',
+    token_count INTEGER NOT NULL DEFAULT 0,
+    embedding_id TEXT,
+    superseded_by TEXT,
+    supersedes TEXT,
+    access_count INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+    updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+    last_accessed_at TEXT,
+    expires_at TEXT,
+    version INTEGER NOT NULL DEFAULT 1,
+    tags TEXT NOT NULL DEFAULT '[]'
+);
+
+-- Indexes for common query patterns
+CREATE INDEX IF NOT EXISTS idx_memories_status ON memories(status);
+CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
+CREATE INDEX IF NOT EXISTS idx_memories_content_hash ON memories(content_hash);
+CREATE INDEX IF NOT EXISTS idx_memories_created_at ON memories(created_at);
+CREATE INDEX IF NOT EXISTS idx_memories_privacy_level ON memories(privacy_level);
+CREATE INDEX IF NOT EXISTS idx_memories_source_type ON memories(source_type);
+CREATE INDEX IF NOT EXISTS idx_memories_provenance ON memories(provenance_event_id);
+
+-- Memory relations (many-to-many)
+CREATE TABLE IF NOT EXISTS memory_relations (
+    id TEXT PRIMARY KEY,
+    source_memory_id TEXT NOT NULL,
+    target_memory_id TEXT NOT NULL,
+    relation_type TEXT NOT NULL,
+    confidence REAL NOT NULL DEFAULT 1.0,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+    metadata TEXT NOT NULL DEFAULT '{}',
+    FOREIGN KEY (source_memory_id) REFERENCES memories(id) ON DELETE CASCADE,
+    FOREIGN KEY (target_memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_relations_source ON memory_relations(source_memory_id);
+CREATE INDEX IF NOT EXISTS idx_relations_target ON memory_relations(target_memory_id);
+CREATE INDEX IF NOT EXISTS idx_relations_type ON memory_relations(relation_type);
+
+-- Raw events: append-only audit log
+CREATE TABLE IF NOT EXISTS events (
+    id TEXT PRIMARY KEY,
+    event_type TEXT NOT NULL,
+    timestamp TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+    source_type TEXT NOT NULL DEFAULT 'system',
+    source_uri TEXT,
+    content TEXT,
+    content_hash TEXT,
+    metadata TEXT NOT NULL DEFAULT '{}',
+    privacy_scan_result TEXT,
+    memory_ids TEXT NOT NULL DEFAULT '[]'
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_type ON events(event_type);
+CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp);
+CREATE INDEX IF NOT EXISTS idx_events_source_type ON events(source_type);
+CREATE INDEX IF NOT EXISTS idx_events_content_hash ON events(content_hash);
+
+-- Pipeline traces
+CREATE TABLE IF NOT EXISTS traces (
+    id TEXT PRIMARY KEY,
+    trace_type TEXT NOT NULL,
+    timestamp TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+    query TEXT,
+    stages TEXT NOT NULL DEFAULT '[]',
+    total_latency_ms REAL NOT NULL DEFAULT 0.0,
+    total_input_tokens INTEGER,
+    total_output_tokens INTEGER,
+    metadata TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_traces_timestamp ON traces(timestamp);
+CREATE INDEX IF NOT EXISTS idx_traces_type ON traces(trace_type);
+"""
+
+MIGRATION_2_SQL = """
+ALTER TABLE memories ADD COLUMN observed_at TEXT;
+ALTER TABLE memories ADD COLUMN valid_from TEXT;
+ALTER TABLE memories ADD COLUMN valid_to TEXT;
+ALTER TABLE memories ADD COLUMN temporal_precision TEXT NOT NULL DEFAULT 'unknown';
+ALTER TABLE memories ADD COLUMN temporal_status TEXT NOT NULL DEFAULT 'unspecified';
+ALTER TABLE memories ADD COLUMN temporal_expression TEXT;
+ALTER TABLE memories ADD COLUMN slot_json TEXT;
+ALTER TABLE memories ADD COLUMN slot_key TEXT;
+ALTER TABLE memories ADD COLUMN uncertain INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN negated INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN resolution_reason TEXT;
+ALTER TABLE memories ADD COLUMN resolution_confidence REAL;
+UPDATE memories SET observed_at = created_at WHERE observed_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_memories_slot_key ON memories(slot_key);
+CREATE INDEX IF NOT EXISTS idx_memories_temporal_status ON memories(temporal_status);
+CREATE INDEX IF NOT EXISTS idx_memories_validity ON memories(valid_from, valid_to);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_relations_unique
+ON memory_relations(source_memory_id, target_memory_id, relation_type);
+"""
+
+MIGRATION_3_SQL = """
+CREATE TABLE IF NOT EXISTS graph_nodes (
+    id TEXT PRIMARY KEY,
+    node_type TEXT NOT NULL,
+    canonical_key TEXT NOT NULL,
+    label TEXT NOT NULL,
+    metadata TEXT NOT NULL DEFAULT '{}',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    UNIQUE(node_type, canonical_key)
+);
+CREATE INDEX IF NOT EXISTS idx_graph_nodes_key
+ON graph_nodes(canonical_key, node_type);
+
+CREATE TABLE IF NOT EXISTS graph_edges (
+    id TEXT PRIMARY KEY,
+    source_node_id TEXT NOT NULL,
+    target_node_id TEXT NOT NULL,
+    relation_type TEXT NOT NULL,
+    confidence REAL NOT NULL CHECK(confidence >= 0 AND confidence <= 1),
+    directed INTEGER NOT NULL DEFAULT 1,
+    scope_key TEXT NOT NULL DEFAULT '',
+    metadata TEXT NOT NULL DEFAULT '{}',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    FOREIGN KEY (source_node_id) REFERENCES graph_nodes(id) ON DELETE CASCADE,
+    FOREIGN KEY (target_node_id) REFERENCES graph_nodes(id) ON DELETE CASCADE,
+    UNIQUE(source_node_id, target_node_id, relation_type, scope_key)
+);
+CREATE INDEX IF NOT EXISTS idx_graph_edges_source ON graph_edges(source_node_id);
+CREATE INDEX IF NOT EXISTS idx_graph_edges_target ON graph_edges(target_node_id);
+CREATE INDEX IF NOT EXISTS idx_graph_edges_type ON graph_edges(relation_type);
+
+CREATE TABLE IF NOT EXISTS graph_edge_supports (
+    edge_id TEXT NOT NULL,
+    memory_id TEXT NOT NULL,
+    confidence REAL NOT NULL CHECK(confidence >= 0 AND confidence <= 1),
+    provenance_event_id TEXT,
+    created_at TEXT NOT NULL,
+    PRIMARY KEY(edge_id, memory_id),
+    FOREIGN KEY (edge_id) REFERENCES graph_edges(id) ON DELETE CASCADE,
+    FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_graph_support_memory
+ON graph_edge_supports(memory_id);
+"""
+
+MIGRATION_4_SQL = """
+-- A persisted dirty bit makes graph freshness checks O(1).  The graph is a
+-- projection, so a crash before it is marked clean merely causes a safe rebuild.
+CREATE TABLE IF NOT EXISTS graph_projection_state (
+    singleton INTEGER PRIMARY KEY CHECK(singleton = 1),
+    dirty INTEGER NOT NULL DEFAULT 1 CHECK(dirty IN (0, 1))
+);
+INSERT OR IGNORE INTO graph_projection_state(singleton, dirty) VALUES (1, 1);
+
+CREATE TRIGGER IF NOT EXISTS trg_graph_dirty_memory_insert
+AFTER INSERT ON memories BEGIN
+    UPDATE graph_projection_state SET dirty = 1 WHERE singleton = 1;
+END;
+CREATE TRIGGER IF NOT EXISTS trg_graph_dirty_memory_update
+AFTER UPDATE ON memories BEGIN
+    UPDATE graph_projection_state SET dirty = 1 WHERE singleton = 1;
+END;
+CREATE TRIGGER IF NOT EXISTS trg_graph_dirty_memory_delete
+AFTER DELETE ON memories BEGIN
+    UPDATE graph_projection_state SET dirty = 1 WHERE singleton = 1;
+END;
+CREATE TRIGGER IF NOT EXISTS trg_graph_dirty_relation_insert
+AFTER INSERT ON memory_relations BEGIN
+    UPDATE graph_projection_state SET dirty = 1 WHERE singleton = 1;
+END;
+CREATE TRIGGER IF NOT EXISTS trg_graph_dirty_relation_update
+AFTER UPDATE ON memory_relations BEGIN
+    UPDATE graph_projection_state SET dirty = 1 WHERE singleton = 1;
+END;
+CREATE TRIGGER IF NOT EXISTS trg_graph_dirty_relation_delete
+AFTER DELETE ON memory_relations BEGIN
+    UPDATE graph_projection_state SET dirty = 1 WHERE singleton = 1;
+END;
+"""
+
+MIGRATION_5_SQL = """
+CREATE TABLE IF NOT EXISTS model_invocations (
+    id TEXT PRIMARY KEY,
+    invocation_id TEXT NOT NULL UNIQUE,
+    session_id TEXT,
+    provider_id TEXT NOT NULL,
+    model_id TEXT NOT NULL,
+    is_local INTEGER NOT NULL DEFAULT 1,
+    timestamp TEXT NOT NULL,
+    candidate_context_tokens INTEGER NOT NULL DEFAULT 0,
+    retrieved_context_tokens INTEGER NOT NULL DEFAULT 0,
+    optimized_context_tokens INTEGER NOT NULL DEFAULT 0,
+    compiled_context_tokens INTEGER NOT NULL DEFAULT 0,
+    prompt_tokens_before_context INTEGER NOT NULL DEFAULT 0,
+    final_input_tokens INTEGER NOT NULL DEFAULT 0,
+    provider_input_tokens INTEGER NOT NULL DEFAULT 0,
+    provider_output_tokens INTEGER NOT NULL DEFAULT 0,
+    provider_total_tokens INTEGER NOT NULL DEFAULT 0,
+    token_measurement_source TEXT NOT NULL,
+    context_tokens_avoided INTEGER NOT NULL DEFAULT 0,
+    reduction_ratio REAL NOT NULL DEFAULT 0.0,
+    lexical_candidate_count INTEGER NOT NULL DEFAULT 0,
+    dense_candidate_count INTEGER NOT NULL DEFAULT 0,
+    hybrid_candidate_count INTEGER NOT NULL DEFAULT 0,
+    graph_expanded_count INTEGER NOT NULL DEFAULT 0,
+    temporal_filtered_count INTEGER NOT NULL DEFAULT 0,
+    selected_memory_count INTEGER NOT NULL DEFAULT 0,
+    compiled_fact_count INTEGER NOT NULL DEFAULT 0,
+    retrieval_ms REAL NOT NULL DEFAULT 0.0,
+    optimization_ms REAL NOT NULL DEFAULT 0.0,
+    compilation_ms REAL NOT NULL DEFAULT 0.0,
+    routing_ms REAL NOT NULL DEFAULT 0.0,
+    token_counting_ms REAL NOT NULL DEFAULT 0.0,
+    provider_latency_ms REAL NOT NULL DEFAULT 0.0,
+    end_to_end_ms REAL NOT NULL DEFAULT 0.0,
+    routing_policy TEXT NOT NULL,
+    routing_reason TEXT NOT NULL,
+    selected_provider TEXT NOT NULL,
+    selected_model TEXT NOT NULL,
+    fallback_used INTEGER NOT NULL DEFAULT 0,
+    fallback_reason TEXT,
+    finish_reason TEXT NOT NULL DEFAULT 'stop',
+    status TEXT NOT NULL DEFAULT 'success',
+    error_code TEXT,
+    metadata TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_invocations_timestamp ON model_invocations(timestamp);
+CREATE INDEX IF NOT EXISTS idx_invocations_provider ON model_invocations(provider_id);
+CREATE INDEX IF NOT EXISTS idx_invocations_model ON model_invocations(model_id);
+CREATE INDEX IF NOT EXISTS idx_invocations_is_local ON model_invocations(is_local);
+"""
+
+MIGRATION_6_SQL = """
+CREATE TABLE IF NOT EXISTS connector_state (
+    connector_id TEXT PRIMARY KEY,
+    connector_type TEXT NOT NULL,
+    cursor TEXT,
+    last_success_at TEXT,
+    last_attempt_at TEXT,
+    enabled INTEGER NOT NULL DEFAULT 1 CHECK(enabled IN (0, 1)),
+    status TEXT NOT NULL DEFAULT 'idle',
+    error_code TEXT
+);
+CREATE TABLE IF NOT EXISTS connector_items (
+    connector_id TEXT NOT NULL,
+    external_id TEXT NOT NULL,
+    revision TEXT NOT NULL,
+    content_hash TEXT NOT NULL,
+    source_uri TEXT NOT NULL,
+    memory_ids TEXT NOT NULL DEFAULT '[]',
+    last_seen_at TEXT NOT NULL,
+    deleted INTEGER NOT NULL DEFAULT 0 CHECK(deleted IN (0, 1)),
+    PRIMARY KEY(connector_id, external_id)
+);
+CREATE INDEX IF NOT EXISTS idx_connector_items_connector ON connector_items(connector_id);
+"""
+
+MIGRATION_7_SQL = """
+ALTER TABLE model_invocations ADD COLUMN context_token_measurement_source TEXT;
+ALTER TABLE model_invocations ADD COLUMN context_tokenizer TEXT;
+CREATE INDEX IF NOT EXISTS idx_invocations_model_recent ON model_invocations(model_id, timestamp DESC);
+"""
+
+
+
+class Database:
+    """Manages the SQLite database connection and schema.
+
+    Usage:
+        db = Database(data_dir / "contextos.db")
+        await db.initialize()
+        # ... use db.connection() to get aiosqlite connection
+        await db.close()
+    """
+
+    def __init__(self, db_path: Path) -> None:
+        self._db_path = db_path
+        self._connection: aiosqlite.Connection | None = None
+
+    @property
+    def path(self) -> Path:
+        return self._db_path
+
+    async def initialize(self) -> None:
+        """Open the database, set pragmas, and run schema migrations."""
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if self._connection is not None:
+            return
+        self._connection = await aiosqlite.connect(
+            str(self._db_path),
+            detect_types=sqlite3.PARSE_DECLTYPES,
+        )
+
+        # Enable WAL mode for concurrent read access and crash resilience
+        await self._connection.execute("PRAGMA journal_mode=WAL")
+
+        # Enable foreign keys
+        await self._connection.execute("PRAGMA foreign_keys=ON")
+
+        # Reasonable busy timeout for concurrent access
+        await self._connection.execute("PRAGMA busy_timeout=5000")
+
+        # Row factory for dict-like access
+        self._connection.row_factory = aiosqlite.Row
+
+        try:
+            await self._apply_schema()
+        except Exception:
+            await self.close()
+            raise
+        logger.info("Database initialized at %s", self._db_path)
+
+    async def _apply_schema(self) -> None:
+        """Apply the initial schema and ordered incremental migrations."""
+        assert self._connection is not None
+
+        # Check if schema_version table exists
+        cursor = await self._connection.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='schema_version'"
+        )
+        table_exists = await cursor.fetchone()
+
+        if not table_exists:
+            try:
+                await self._connection.executescript(
+                    "BEGIN IMMEDIATE;\n" + SCHEMA_SQL
+                    + "\nINSERT INTO schema_version (version, description) "
+                    "VALUES (1, 'Initial schema');\nCOMMIT;"
+                )
+            except Exception as exc:
+                await self._connection.rollback()
+                raise MigrationError("Failed to initialize database schema") from exc
+            current_version = 1
+        else:
+            cursor = await self._connection.execute(
+                "SELECT MAX(version) FROM schema_version"
+            )
+            row = await cursor.fetchone()
+            current_version = row[0] if row and row[0] is not None else 0
+
+            if current_version > SCHEMA_VERSION:
+                raise MigrationError(
+                    f"Database schema version {current_version} is newer than supported {SCHEMA_VERSION}"
+                )
+        if current_version < 2:
+            try:
+                await self._connection.executescript(
+                    "BEGIN IMMEDIATE;\n" + MIGRATION_2_SQL
+                    + "\nINSERT INTO schema_version (version, description) "
+                    "VALUES (2, 'Temporal memory and resolution metadata');\nCOMMIT;"
+                )
+            except Exception as exc:
+                await self._connection.rollback()
+                raise MigrationError("Failed to apply schema migration 2") from exc
+            current_version = 2
+
+        if current_version < 3:
+            try:
+                await self._connection.executescript(
+                    "BEGIN IMMEDIATE;\n" + MIGRATION_3_SQL
+                    + "\nINSERT INTO schema_version (version, description) "
+                    "VALUES (3, 'Memory graph projection and edge provenance');\nCOMMIT;"
+                )
+            except Exception as exc:
+                await self._connection.rollback()
+                raise MigrationError("Failed to apply schema migration 3") from exc
+            current_version = 3
+
+        if current_version < 4:
+            try:
+                await self._connection.executescript(
+                    "BEGIN IMMEDIATE;\n" + MIGRATION_4_SQL
+                    + "\nINSERT INTO schema_version (version, description) "
+                    "VALUES (4, 'Graph projection freshness tracking');\nCOMMIT;"
+                )
+            except Exception as exc:
+                await self._connection.rollback()
+                raise MigrationError("Failed to apply schema migration 4") from exc
+            current_version = 4
+
+        if current_version < 5:
+            try:
+                await self._connection.executescript(
+                    "BEGIN IMMEDIATE;\n" + MIGRATION_5_SQL
+                    + "\nINSERT INTO schema_version (version, description) "
+                    "VALUES (5, 'Model invocation telemetry persistence');\nCOMMIT;"
+                )
+            except Exception as exc:
+                await self._connection.rollback()
+                raise MigrationError("Failed to apply schema migration 5") from exc
+            current_version = 5
+
+        if current_version < 6:
+            try:
+                await self._connection.executescript(
+                    "BEGIN IMMEDIATE;\n" + MIGRATION_6_SQL
+                    + "\nINSERT INTO schema_version (version, description) "
+                    "VALUES (6, 'Connector sync state and source item identity');\nCOMMIT;"
+                )
+            except Exception as exc:
+                await self._connection.rollback()
+                raise MigrationError("Failed to apply schema migration 6") from exc
+            current_version = 6
+
+        if current_version < 7:
+            try:
+                await self._connection.executescript(
+                    "BEGIN IMMEDIATE;\n" + MIGRATION_7_SQL
+                    + "\nINSERT INTO schema_version (version, description) "
+                    "VALUES (7, 'Context token counting provenance');\nCOMMIT;"
+                )
+            except Exception as exc:
+                await self._connection.rollback()
+                raise MigrationError("Failed to apply schema migration 7") from exc
+            current_version = 7
+
+
+        if current_version != SCHEMA_VERSION:
+            raise MigrationError(
+                f"Database schema version {current_version} is unsupported"
+            )
+        logger.info("Applied schema version %d", SCHEMA_VERSION)
+
+    def connection(self) -> aiosqlite.Connection:
+        """Get the database connection. Raises if not initialized."""
+        if self._connection is None:
+            raise RuntimeError(
+                "Database not initialized. Call await db.initialize() first."
+            )
+        return self._connection
+
+    async def close(self) -> None:
+        """Close the database connection."""
+        if self._connection is not None:
+            await self._connection.close()
+            self._connection = None
+            logger.info("Database connection closed")
+
+    async def integrity_check(self) -> tuple[bool, str]:
+        """Run SQLite integrity check. Returns (ok, message)."""
+        conn = self.connection()
+        cursor = await conn.execute("PRAGMA integrity_check")
+        row = await cursor.fetchone()
+        result = row[0] if row else "unknown"
+        return result == "ok", result
+
+    async def get_size_bytes(self) -> int:
+        """Get database file size in bytes."""
+        if self._db_path.exists():
+            return self._db_path.stat().st_size
+        return 0

contextos/storage/event_repo.py

@@ -0,0 +1,137 @@
+"""SQLite-backed Event repository.
+
+Implements the EventRepository protocol. Events are append-only — the only
+mutation is purge, which physically removes the row.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from uuid import UUID
+
+import aiosqlite
+
+from contextos.core.enums import EventType
+from contextos.core.models import EventFilters, RawEvent
+
+logger = logging.getLogger(__name__)
+
+
+def _row_to_event(row: aiosqlite.Row) -> RawEvent:
+    """Convert a SQLite row to a RawEvent model."""
+    data = dict(row)
+
+    data["id"] = UUID(data["id"])
+    data["event_type"] = EventType(data["event_type"])
+
+    # Parse JSON fields
+    data["metadata"] = json.loads(data.get("metadata", "{}"))
+    data["memory_ids"] = [UUID(mid) for mid in json.loads(data.get("memory_ids", "[]"))]
+
+    pscan = data.get("privacy_scan_result")
+    data["privacy_scan_result"] = json.loads(pscan) if pscan else None
+
+    # Parse timestamp
+    ts = data.get("timestamp")
+    if ts is not None:
+        data["timestamp"] = datetime.fromisoformat(ts).replace(tzinfo=timezone.utc)
+
+    return RawEvent.model_validate(data)
+
+
+def _event_to_row(event: RawEvent) -> dict:
+    """Convert a RawEvent model to a dict suitable for SQLite insertion."""
+    return {
+        "id": str(event.id),
+        "event_type": event.event_type.value,
+        "timestamp": event.timestamp.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "source_type": event.source_type,
+        "source_uri": event.source_uri,
+        "content": event.content,
+        "content_hash": event.content_hash,
+        "metadata": json.dumps(event.metadata),
+        "privacy_scan_result": (
+            json.dumps(event.privacy_scan_result)
+            if event.privacy_scan_result is not None
+            else None
+        ),
+        "memory_ids": json.dumps([str(mid) for mid in event.memory_ids]),
+    }
+
+
+class SqliteEventRepository:
+    """SQLite implementation of the EventRepository protocol."""
+
+    def __init__(self, db: aiosqlite.Connection) -> None:
+        self._db = db
+
+    async def append(self, event: RawEvent) -> None:
+        row = _event_to_row(event)
+        columns = ", ".join(row.keys())
+        placeholders = ", ".join("?" for _ in row)
+
+        await self._db.execute(
+            f"INSERT INTO events ({columns}) VALUES ({placeholders})",
+            list(row.values()),
+        )
+        await self._db.commit()
+        logger.debug("Appended event %s (type: %s)", event.id, event.event_type.value)
+
+    async def get(self, event_id: UUID) -> RawEvent | None:
+        cursor = await self._db.execute(
+            "SELECT * FROM events WHERE id = ?", (str(event_id),)
+        )
+        row = await cursor.fetchone()
+        if row is None:
+            return None
+        return _row_to_event(row)
+
+    async def list(self, filters: EventFilters) -> list[RawEvent]:
+        query = "SELECT * FROM events WHERE 1=1"
+        params: list = []
+
+        if filters.event_type is not None:
+            query += " AND event_type = ?"
+            params.append(filters.event_type.value)
+
+        if filters.source_type is not None:
+            query += " AND source_type = ?"
+            params.append(filters.source_type)
+
+        if filters.after is not None:
+            query += " AND timestamp >= ?"
+            params.append(filters.after.strftime("%Y-%m-%dT%H:%M:%SZ"))
+
+        if filters.before is not None:
+            query += " AND timestamp <= ?"
+            params.append(filters.before.strftime("%Y-%m-%dT%H:%M:%SZ"))
+
+        if filters.memory_id is not None:
+            # Search for memory_id within the JSON array
+            query += " AND EXISTS (SELECT 1 FROM json_each(memory_ids) WHERE value = ?)"
+            params.append(str(filters.memory_id))
+
+        query += " ORDER BY timestamp DESC LIMIT ? OFFSET ?"
+        params.extend([filters.limit, filters.offset])
+
+        cursor = await self._db.execute(query, params)
+        rows = await cursor.fetchall()
+        return [_row_to_event(row) for row in rows]
+
+    async def count(self, filters: EventFilters | None = None) -> int:
+        if filters is None:
+            cursor = await self._db.execute("SELECT COUNT(*) FROM events")
+        else:
+            query = "SELECT COUNT(*) FROM events WHERE 1=1"
+            params: list = []
+
+            if filters.event_type is not None:
+                query += " AND event_type = ?"
+                params.append(filters.event_type.value)
+
+            cursor = await self._db.execute(query, params)
+
+        row = await cursor.fetchone()
+        return row[0] if row else 0