opencode-semantic-memory 0.1.0__py3-none-any.whl

opencode_memory/storage/sqlite.py

@@ -0,0 +1,1608 @@
+"""SQLite storage for entities, memories, and sessions."""
+
+import json
+import sqlite3
+import threading
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from opencode_memory.models import (
+    Entity,
+    EntityType,
+    LinkType,
+    Memory,
+    MemoryCategory,
+    MemoryLink,
+    Session,
+)
+
+
+def _format_age_from_iso(iso_str: str) -> str:
+    """Format age from ISO datetime string."""
+    created_at = datetime.fromisoformat(iso_str)
+    if created_at.tzinfo is None:
+        created_at = created_at.replace(tzinfo=UTC)
+
+    now = datetime.now(UTC)
+    delta = now - created_at
+    days = delta.days
+
+    if days == 0:
+        hours = delta.seconds // 3600
+        if hours == 0:
+            minutes = delta.seconds // 60
+            return f"{minutes}m" if minutes > 0 else "now"
+        return f"{hours}h"
+    elif days == 1:
+        return "1d"
+    elif days < 7:
+        return f"{days}d"
+    elif days < 30:
+        return f"{days // 7}w"
+    elif days < 365:
+        return f"{days // 30}mo"
+    else:
+        return f"{days // 365}y"
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS entities (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    type TEXT NOT NULL,
+    ref TEXT NOT NULL,
+    project TEXT,
+    title TEXT,
+    metadata TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    last_mentioned_at TEXT,
+    last_enriched_at TEXT,
+    UNIQUE(type, ref, project)
+);
+
+CREATE TABLE IF NOT EXISTS memories (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_file TEXT,
+    source_line INTEGER,
+    project TEXT,
+    category TEXT NOT NULL,
+    content TEXT NOT NULL,
+    what TEXT,
+    why TEXT,
+    learned TEXT,
+    created_at TEXT NOT NULL,
+    expires_at TEXT,
+    resolved_at TEXT,
+    embedding_id TEXT
+);
+
+CREATE TABLE IF NOT EXISTS entity_memories (
+    entity_id INTEGER NOT NULL,
+    memory_id INTEGER NOT NULL,
+    relationship TEXT DEFAULT 'about',
+    PRIMARY KEY (entity_id, memory_id),
+    FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+    FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    started_at TEXT NOT NULL,
+    last_heartbeat TEXT NOT NULL,
+    working_on TEXT,
+    claimed_items TEXT
+);
+
+CREATE TABLE IF NOT EXISTS ingest_state (
+    source TEXT PRIMARY KEY,
+    last_processed TEXT,
+    last_id TEXT,
+    metadata TEXT
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+    content, what, why, learned,
+    content='memories',
+    content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts(rowid, content, what, why, learned)
+    VALUES (new.id, new.content, new.what, new.why, new.learned);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, content, what, why, learned)
+    VALUES ('delete', old.id, old.content, old.what, old.why, old.learned);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, content, what, why, learned)
+    VALUES ('delete', old.id, old.content, old.what, old.why, old.learned);
+    INSERT INTO memories_fts(rowid, content, what, why, learned)
+    VALUES (new.id, new.content, new.what, new.why, new.learned);
+END;
+
+CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type);
+CREATE INDEX IF NOT EXISTS idx_entities_ref ON entities(ref);
+CREATE INDEX IF NOT EXISTS idx_entities_last_mentioned ON entities(last_mentioned_at);
+CREATE INDEX IF NOT EXISTS idx_entities_last_enriched ON entities(last_enriched_at);
+CREATE INDEX IF NOT EXISTS idx_memories_category ON memories(category);
+CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(created_at);
+CREATE INDEX IF NOT EXISTS idx_memories_resolved ON memories(resolved_at);
+CREATE INDEX IF NOT EXISTS idx_memories_expires ON memories(expires_at);
+CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project);
+
+CREATE TABLE IF NOT EXISTS archived_memories (
+    id INTEGER PRIMARY KEY,
+    source_file TEXT,
+    source_line INTEGER,
+    category TEXT NOT NULL,
+    content TEXT NOT NULL,
+    what TEXT,
+    why TEXT,
+    learned TEXT,
+    created_at TEXT NOT NULL,
+    expires_at TEXT,
+    resolved_at TEXT,
+    archived_at TEXT NOT NULL,
+    archive_reason TEXT
+);
+
+CREATE TABLE IF NOT EXISTS memory_links (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_memory_id INTEGER NOT NULL,
+    target_memory_id INTEGER NOT NULL,
+    link_type TEXT NOT NULL,
+    strength REAL DEFAULT 0.5,
+    reason TEXT,
+    created_at TEXT NOT NULL,
+    FOREIGN KEY (source_memory_id) REFERENCES memories(id) ON DELETE CASCADE,
+    FOREIGN KEY (target_memory_id) REFERENCES memories(id) ON DELETE CASCADE,
+    UNIQUE(source_memory_id, target_memory_id, link_type)
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_links_source ON memory_links(source_memory_id);
+CREATE INDEX IF NOT EXISTS idx_memory_links_target ON memory_links(target_memory_id);
+CREATE INDEX IF NOT EXISTS idx_memory_links_type ON memory_links(link_type);
+
+-- Composite index for common query pattern: category + project filtering
+CREATE INDEX IF NOT EXISTS idx_memories_category_project ON memories(category, project);
+"""
+
+
+class SQLiteStorage:
+    """SQLite-based storage for memories and entities.
+
+    Uses thread-local connections to avoid "database is locked" errors
+    under concurrent access while maintaining connection reuse.
+    """
+
+    def __init__(self, db_path: Path):
+        self.db_path = db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._local = threading.local()
+        self._init_db()
+
+    def _init_db(self) -> None:
+        """Initialize database schema."""
+        with sqlite3.connect(self.db_path) as conn:
+            self._run_migrations(conn)
+            conn.executescript(SCHEMA)
+
+    def _run_migrations(self, conn: sqlite3.Connection) -> None:
+        """Run any needed schema migrations before full schema creation."""
+        # Migrate memories table
+        try:
+            cursor = conn.execute("PRAGMA table_info(memories)")
+            columns = {row[1] for row in cursor.fetchall()}
+        except Exception:
+            columns = set()
+
+        if columns and "project" not in columns:
+            conn.execute("ALTER TABLE memories ADD COLUMN project TEXT")
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project)")
+
+        # Migrate entities table
+        try:
+            cursor = conn.execute("PRAGMA table_info(entities)")
+            entity_columns = {row[1] for row in cursor.fetchall()}
+        except Exception:
+            entity_columns = set()
+
+        if entity_columns:
+            if "last_mentioned_at" not in entity_columns:
+                conn.execute("ALTER TABLE entities ADD COLUMN last_mentioned_at TEXT")
+                conn.execute(
+                    "CREATE INDEX IF NOT EXISTS idx_entities_last_mentioned ON entities(last_mentioned_at)"
+                )
+                # Initialize from most recent memory mention
+                conn.execute("""
+                    UPDATE entities SET last_mentioned_at = (
+                        SELECT MAX(m.created_at) FROM memories m
+                        JOIN entity_memories em ON em.memory_id = m.id
+                        WHERE em.entity_id = entities.id
+                    )
+                """)
+
+            if "last_enriched_at" not in entity_columns:
+                conn.execute("ALTER TABLE entities ADD COLUMN last_enriched_at TEXT")
+                conn.execute(
+                    "CREATE INDEX IF NOT EXISTS idx_entities_last_enriched ON entities(last_enriched_at)"
+                )
+                # Initialize from updated_at for entities with metadata
+                conn.execute("""
+                    UPDATE entities SET last_enriched_at = updated_at
+                    WHERE metadata IS NOT NULL
+                """)
+
+    def _get_conn(self) -> sqlite3.Connection:
+        """Get a thread-local database connection.
+
+        Reuses connections per-thread to avoid overhead and lock contention.
+        """
+        conn = getattr(self._local, "conn", None)
+        if conn is None:
+            conn = sqlite3.connect(self.db_path, timeout=30.0)
+            conn.row_factory = sqlite3.Row
+            conn.execute("PRAGMA journal_mode=WAL")  # Better concurrency
+            conn.execute("PRAGMA busy_timeout=30000")  # 30s timeout
+            self._local.conn = conn
+        return conn
+
+    def upsert_entity(self, entity: Entity) -> int:
+        """Insert or update an entity, return its ID."""
+        metadata_json = json.dumps(entity.metadata) if entity.metadata else None
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                INSERT INTO entities (type, ref, project, title, metadata, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(type, ref, project) DO UPDATE SET
+                    title = COALESCE(excluded.title, entities.title),
+                    metadata = COALESCE(excluded.metadata, entities.metadata),
+                    updated_at = excluded.updated_at
+                RETURNING id
+                """,
+                (
+                    entity.type.value,
+                    entity.ref,
+                    entity.project,
+                    entity.title,
+                    metadata_json,
+                    entity.created_at.isoformat(),
+                    entity.updated_at.isoformat(),
+                ),
+            )
+            row = cursor.fetchone()
+            return int(row[0])
+
+    def get_entity(self, ref: str, entity_type: EntityType | None = None) -> Entity | None:
+        """Get an entity by reference."""
+        with self._get_conn() as conn:
+            if entity_type:
+                cursor = conn.execute(
+                    "SELECT * FROM entities WHERE ref = ? AND type = ?",
+                    (ref, entity_type.value),
+                )
+            else:
+                cursor = conn.execute("SELECT * FROM entities WHERE ref = ?", (ref,))
+            row = cursor.fetchone()
+            if row:
+                metadata = {}
+                if row["metadata"]:
+                    try:
+                        metadata = json.loads(row["metadata"])
+                    except json.JSONDecodeError:
+                        pass
+                return Entity(
+                    id=row["id"],
+                    type=EntityType(row["type"]),
+                    ref=row["ref"],
+                    project=row["project"],
+                    title=row["title"],
+                    metadata=metadata,
+                    created_at=datetime.fromisoformat(row["created_at"]),
+                    updated_at=datetime.fromisoformat(row["updated_at"]),
+                )
+            return None
+
+    def insert_memory(self, memory: Memory, entity_ids: list[int] | None = None) -> int:
+        """Insert a memory and link to entities.
+
+        Returns existing memory ID if duplicate content exists (same category + content prefix).
+        """
+        with self._get_conn() as conn:
+            # Check for duplicate: same category and content prefix (first 500 chars)
+            content_prefix = memory.content[:500] if memory.content else ""
+            cursor = conn.execute(
+                """
+                SELECT id FROM memories 
+                WHERE category = ? AND SUBSTR(content, 1, 500) = ?
+                LIMIT 1
+                """,
+                (memory.category.value, content_prefix),
+            )
+            existing = cursor.fetchone()
+            if existing:
+                # Silently return existing ID instead of creating duplicate
+                return int(existing[0])
+
+            cursor = conn.execute(
+                """
+                INSERT INTO memories 
+                (source_file, source_line, project, category, content, what, why, learned,
+                 created_at, expires_at, resolved_at, embedding_id)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                RETURNING id
+                """,
+                (
+                    memory.source_file,
+                    memory.source_line,
+                    memory.project,
+                    memory.category.value,
+                    memory.content,
+                    memory.what,
+                    memory.why,
+                    memory.learned,
+                    memory.created_at.isoformat(),
+                    memory.expires_at.isoformat() if memory.expires_at else None,
+                    memory.resolved_at.isoformat() if memory.resolved_at else None,
+                    memory.embedding_id,
+                ),
+            )
+            memory_id = int(cursor.fetchone()[0])
+
+            if entity_ids:
+                now = datetime.now(UTC).isoformat()
+                for entity_id in entity_ids:
+                    conn.execute(
+                        "INSERT OR IGNORE INTO entity_memories (entity_id, memory_id) VALUES (?, ?)",
+                        (entity_id, memory_id),
+                    )
+                # Update last_mentioned_at for all linked entities
+                conn.execute(
+                    f"""
+                    UPDATE entities SET last_mentioned_at = ?
+                    WHERE id IN ({",".join("?" * len(entity_ids))})
+                    """,
+                    [now] + list(entity_ids),
+                )
+
+            return memory_id
+
+    def _sanitize_fts_term(self, word: str) -> str:
+        """Escape quotes in FTS5 search terms to prevent injection."""
+        return '"' + word.replace('"', '""') + '"'
+
+    def search_fts(self, query: str, limit: int = 20, project: str | None = None) -> list[Memory]:
+        """Full-text search across memories, optionally filtered by project.
+
+        Automatically excludes expired and archived memories.
+        """
+        fts_query = " OR ".join(self._sanitize_fts_term(word) for word in query.split() if word)
+        with self._get_conn() as conn:
+            if project:
+                cursor = conn.execute(
+                    """
+                    SELECT m.*, bm25(memories_fts) as score
+                    FROM memories_fts
+                    JOIN memories m ON memories_fts.rowid = m.id
+                    WHERE memories_fts MATCH ? 
+                      AND m.project = ?
+                      AND (m.expires_at IS NULL OR m.expires_at > datetime('now'))
+                      AND m.id NOT IN (SELECT id FROM archived_memories)
+                    ORDER BY score
+                    LIMIT ?
+                    """,
+                    (fts_query, project, limit),
+                )
+            else:
+                cursor = conn.execute(
+                    """
+                    SELECT m.*, bm25(memories_fts) as score
+                    FROM memories_fts
+                    JOIN memories m ON memories_fts.rowid = m.id
+                    WHERE memories_fts MATCH ?
+                      AND (m.expires_at IS NULL OR m.expires_at > datetime('now'))
+                      AND m.id NOT IN (SELECT id FROM archived_memories)
+                    ORDER BY score
+                    LIMIT ?
+                    """,
+                    (fts_query, limit),
+                )
+            return [self._row_to_memory(row) for row in cursor.fetchall()]
+
+    def get_memory_by_id(self, memory_id: int) -> Memory | None:
+        """Get a single memory by ID."""
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                "SELECT * FROM memories WHERE id = ?",
+                (memory_id,),
+            )
+            row = cursor.fetchone()
+            return self._row_to_memory(row) if row else None
+
+    def delete_memory(self, memory_id: int) -> bool:
+        """Permanently delete a memory and its associations.
+
+        This is a hard delete - use archive_memory for soft delete.
+        Also removes from FTS index, entity links, and memory links.
+        """
+        with self._get_conn() as conn:
+            # Check if exists
+            cursor = conn.execute("SELECT id FROM memories WHERE id = ?", (memory_id,))
+            if not cursor.fetchone():
+                return False
+
+            # Delete entity links first
+            conn.execute("DELETE FROM entity_memories WHERE memory_id = ?", (memory_id,))
+
+            # Delete memory links (both directions)
+            conn.execute(
+                "DELETE FROM memory_links WHERE source_memory_id = ? OR target_memory_id = ?",
+                (memory_id, memory_id),
+            )
+
+            # Delete the memory itself (FTS is handled by trigger)
+            cursor = conn.execute("DELETE FROM memories WHERE id = ?", (memory_id,))
+            return cursor.rowcount > 0
+
+    def update_memory(
+        self,
+        memory_id: int,
+        content: str | None = None,
+        what: str | None = None,
+        why: str | None = None,
+        learned: str | None = None,
+        category: str | None = None,
+    ) -> bool:
+        """Update a memory's content or metadata.
+
+        Only provided (non-None) fields are updated.
+        Also updates FTS index if content changes.
+        """
+        memory = self.get_memory_by_id(memory_id)
+        if not memory:
+            return False
+
+        updates = []
+        params = []
+
+        if content is not None:
+            updates.append("content = ?")
+            params.append(content)
+        if what is not None:
+            updates.append("what = ?")
+            params.append(what)
+        if why is not None:
+            updates.append("why = ?")
+            params.append(why)
+        if learned is not None:
+            updates.append("learned = ?")
+            params.append(learned)
+        if category is not None:
+            updates.append("category = ?")
+            params.append(category)
+
+        if not updates:
+            return True  # Nothing to update
+
+        params.append(memory_id)
+
+        with self._get_conn() as conn:
+            conn.execute(
+                f"UPDATE memories SET {', '.join(updates)} WHERE id = ?",
+                params,
+            )
+
+            # Update FTS index if content changed
+            if content is not None:
+                conn.execute("DELETE FROM memories_fts WHERE rowid = ?", (memory_id,))
+                conn.execute(
+                    "INSERT INTO memories_fts(rowid, content) VALUES (?, ?)",
+                    (memory_id, content),
+                )
+
+            return True
+
+    def get_memories_by_ids(
+        self, memory_ids: list[int], exclude_expired: bool = True
+    ) -> dict[int, Memory]:
+        """Get multiple memories by IDs in a single query. Returns dict of id -> Memory.
+
+        By default excludes expired and archived memories.
+        """
+        if not memory_ids:
+            return {}
+        with self._get_conn() as conn:
+            placeholders = ",".join("?" * len(memory_ids))
+            if exclude_expired:
+                cursor = conn.execute(
+                    f"""
+                    SELECT * FROM memories 
+                    WHERE id IN ({placeholders})
+                      AND (expires_at IS NULL OR expires_at > datetime('now'))
+                      AND id NOT IN (SELECT id FROM archived_memories)
+                    """,
+                    memory_ids,
+                )
+            else:
+                cursor = conn.execute(
+                    f"SELECT * FROM memories WHERE id IN ({placeholders})",
+                    memory_ids,
+                )
+            return {row["id"]: self._row_to_memory(row) for row in cursor.fetchall()}
+
+    def get_memories_for_entity(self, entity_id: int) -> list[Memory]:
+        """Get all memories linked to an entity."""
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT m.* FROM memories m
+                JOIN entity_memories em ON m.id = em.memory_id
+                WHERE em.entity_id = ?
+                ORDER BY m.created_at DESC
+                """,
+                (entity_id,),
+            )
+            return [self._row_to_memory(row) for row in cursor.fetchall()]
+
+    def get_all_memories(
+        self, project: str | None = None, include_archived: bool = False, limit: int = 1000
+    ) -> list[Memory]:
+        """Get all memories, optionally filtered by project."""
+        with self._get_conn() as conn:
+            if project:
+                if include_archived:
+                    cursor = conn.execute(
+                        "SELECT * FROM memories WHERE project = ? ORDER BY created_at DESC LIMIT ?",
+                        (project, limit),
+                    )
+                else:
+                    cursor = conn.execute(
+                        """
+                        SELECT * FROM memories 
+                        WHERE project = ? AND id NOT IN (SELECT id FROM archived_memories)
+                        ORDER BY created_at DESC LIMIT ?
+                        """,
+                        (project, limit),
+                    )
+            else:
+                if include_archived:
+                    cursor = conn.execute(
+                        "SELECT * FROM memories ORDER BY created_at DESC LIMIT ?",
+                        (limit,),
+                    )
+                else:
+                    cursor = conn.execute(
+                        """
+                        SELECT * FROM memories 
+                        WHERE id NOT IN (SELECT id FROM archived_memories)
+                        ORDER BY created_at DESC LIMIT ?
+                        """,
+                        (limit,),
+                    )
+            return [self._row_to_memory(row) for row in cursor.fetchall()]
+
+    def get_memories_by_category(
+        self,
+        category: MemoryCategory,
+        limit: int = 50,
+        include_resolved: bool = False,
+        project: str | None = None,
+    ) -> list[Memory]:
+        """Get memories by category, optionally filtered by project."""
+        with self._get_conn() as conn:
+            conditions = ["category = ?"]
+            params: list[Any] = [category.value]
+
+            if not include_resolved:
+                conditions.append("resolved_at IS NULL")
+
+            if project:
+                conditions.append("project = ?")
+                params.append(project)
+
+            params.append(limit)
+            query = f"""
+                SELECT * FROM memories
+                WHERE {" AND ".join(conditions)}
+                ORDER BY created_at DESC
+                LIMIT ?
+            """
+            cursor = conn.execute(query, params)
+            return [self._row_to_memory(row) for row in cursor.fetchall()]
+
+    def get_directives_for_context(
+        self, current_project: str | None, limit: int = 20
+    ) -> list[Memory]:
+        """Get directives: global (project IS NULL) + current project specific.
+
+        Returns directives that either:
+        - Have no project (global, apply everywhere)
+        - Match the current project exactly
+        """
+        with self._get_conn() as conn:
+            if current_project:
+                query = """
+                    SELECT * FROM memories
+                    WHERE category = ? AND resolved_at IS NULL
+                      AND (project IS NULL OR project = ?)
+                    ORDER BY 
+                      CASE WHEN project IS NULL THEN 1 ELSE 0 END,
+                      created_at DESC
+                    LIMIT ?
+                """
+                params = [MemoryCategory.DIRECTIVE.value, current_project, limit]
+            else:
+                # No project context - only return global directives
+                query = """
+                    SELECT * FROM memories
+                    WHERE category = ? AND resolved_at IS NULL AND project IS NULL
+                    ORDER BY created_at DESC
+                    LIMIT ?
+                """
+                params = [MemoryCategory.DIRECTIVE.value, limit]
+
+            cursor = conn.execute(query, params)
+            return [self._row_to_memory(row) for row in cursor.fetchall()]
+
+    def get_plan_summaries(self) -> list[dict[str, Any]]:
+        """Get summary of active plans grouped by project.
+
+        Returns list of {project, count, plans: [{id, what, age}]}
+        """
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT id, project, what, created_at FROM memories
+                WHERE category = 'plan' 
+                  AND resolved_at IS NULL
+                  AND id NOT IN (SELECT id FROM archived_memories)
+                ORDER BY project, created_at DESC
+                """
+            )
+            rows = cursor.fetchall()
+
+        # Group by project
+        by_project: dict[str | None, list[dict]] = {}
+        for row in rows:
+            project = row["project"]
+            if project not in by_project:
+                by_project[project] = []
+            by_project[project].append(
+                {
+                    "id": row["id"],
+                    "what": row["what"],
+                    "age": _format_age_from_iso(row["created_at"]),
+                }
+            )
+
+        return [
+            {
+                "project": project or "global",
+                "count": len(plans),
+                "plans": plans[:3],  # Show max 3 per project
+            }
+            for project, plans in sorted(by_project.items(), key=lambda x: (x[0] is None, x[0]))
+        ]
+
+    def resolve_memory(self, memory_id: int) -> bool:
+        """Mark a memory as resolved."""
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                "UPDATE memories SET resolved_at = ? WHERE id = ? AND resolved_at IS NULL",
+                (datetime.now(UTC).isoformat(), memory_id),
+            )
+            return cursor.rowcount > 0
+
+    def unresolve_memory(self, memory_id: int) -> bool:
+        """Mark a memory as unresolved."""
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                "UPDATE memories SET resolved_at = NULL WHERE id = ?",
+                (memory_id,),
+            )
+            return cursor.rowcount > 0
+
+    def _row_to_memory(self, row: sqlite3.Row) -> Memory:
+        """Convert a database row to a Memory object."""
+        resolved_at = None
+        if "resolved_at" in row.keys() and row["resolved_at"]:
+            resolved_at = datetime.fromisoformat(row["resolved_at"])
+        project = row["project"] if "project" in row.keys() else None
+        return Memory(
+            id=row["id"],
+            source_file=row["source_file"],
+            source_line=row["source_line"],
+            project=project,
+            category=MemoryCategory(row["category"]),
+            content=row["content"],
+            what=row["what"],
+            why=row["why"],
+            learned=row["learned"],
+            created_at=datetime.fromisoformat(row["created_at"]),
+            expires_at=datetime.fromisoformat(row["expires_at"]) if row["expires_at"] else None,
+            resolved_at=resolved_at,
+            embedding_id=row["embedding_id"],
+        )
+
+    def upsert_session(self, session: Session) -> None:
+        """Insert or update a session."""
+        with self._get_conn() as conn:
+            conn.execute(
+                """
+                INSERT INTO sessions (id, started_at, last_heartbeat, working_on, claimed_items)
+                VALUES (?, ?, ?, ?, ?)
+                ON CONFLICT(id) DO UPDATE SET
+                    last_heartbeat = excluded.last_heartbeat,
+                    working_on = excluded.working_on,
+                    claimed_items = excluded.claimed_items
+                """,
+                (
+                    session.id,
+                    session.started_at.isoformat(),
+                    session.last_heartbeat.isoformat(),
+                    session.working_on,
+                    ",".join(session.claimed_items) if session.claimed_items else None,
+                ),
+            )
+
+    def get_active_sessions(self, stale_minutes: int = 30) -> list[Session]:
+        """Get sessions with recent heartbeats."""
+        cutoff = datetime.now(UTC).timestamp() - (stale_minutes * 60)
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT * FROM sessions
+                WHERE datetime(last_heartbeat) > datetime(?, 'unixepoch')
+                """,
+                (cutoff,),
+            )
+            sessions = []
+            for row in cursor.fetchall():
+                sessions.append(
+                    Session(
+                        id=row["id"],
+                        started_at=datetime.fromisoformat(row["started_at"]),
+                        last_heartbeat=datetime.fromisoformat(row["last_heartbeat"]),
+                        working_on=row["working_on"],
+                        claimed_items=row["claimed_items"].split(",")
+                        if row["claimed_items"]
+                        else [],
+                    )
+                )
+            return sessions
+
+    def delete_session(self, session_id: str) -> None:
+        """Delete a session."""
+        with self._get_conn() as conn:
+            conn.execute("DELETE FROM sessions WHERE id = ?", (session_id,))
+
+    def atomic_claim_item(self, session_id: str, item_ref: str) -> tuple[bool, str | None]:
+        """Atomically claim an item for a session.
+
+        Returns (success, current_owner). If success is False, current_owner
+        contains the session_id that owns the item.
+
+        Uses BEGIN IMMEDIATE with retry logic to handle database contention
+        without blocking for long periods.
+        """
+        import time
+
+        max_retries = 3
+        retry_delay = 0.1  # 100ms between retries
+
+        for attempt in range(max_retries):
+            conn = self._get_conn()
+            try:
+                # Set a short busy timeout for this transaction
+                conn.execute("PRAGMA busy_timeout=1000")  # 1 second
+
+                # BEGIN IMMEDIATE acquires write lock immediately
+                conn.execute("BEGIN IMMEDIATE")
+
+                # Check if any other session has this item claimed
+                cursor = conn.execute(
+                    """
+                    SELECT id, claimed_items FROM sessions 
+                    WHERE claimed_items LIKE ? AND id != ?
+                    """,
+                    (f"%{item_ref}%", session_id),
+                )
+                for row in cursor.fetchall():
+                    claimed = row["claimed_items"].split(",") if row["claimed_items"] else []
+                    if item_ref in claimed:
+                        conn.execute("ROLLBACK")
+                        # Restore default timeout
+                        conn.execute("PRAGMA busy_timeout=30000")
+                        return False, row["id"]
+
+                # Get current session's claims
+                cursor = conn.execute(
+                    "SELECT claimed_items FROM sessions WHERE id = ?",
+                    (session_id,),
+                )
+                row = cursor.fetchone()
+
+                if row:
+                    current_claims = row["claimed_items"].split(",") if row["claimed_items"] else []
+                    if item_ref not in current_claims:
+                        current_claims.append(item_ref)
+                    conn.execute(
+                        "UPDATE sessions SET claimed_items = ? WHERE id = ?",
+                        (",".join(current_claims), session_id),
+                    )
+                else:
+                    # Session doesn't exist, create it
+                    now = datetime.now(UTC).isoformat()
+                    conn.execute(
+                        """
+                        INSERT INTO sessions (id, started_at, last_heartbeat, claimed_items)
+                        VALUES (?, ?, ?, ?)
+                        """,
+                        (session_id, now, now, item_ref),
+                    )
+
+                conn.execute("COMMIT")
+                # Restore default timeout
+                conn.execute("PRAGMA busy_timeout=30000")
+                return True, None
+
+            except sqlite3.OperationalError as e:
+                try:
+                    conn.execute("ROLLBACK")
+                except Exception:
+                    pass
+                # Restore default timeout
+                try:
+                    conn.execute("PRAGMA busy_timeout=30000")
+                except Exception:
+                    pass
+
+                if "database is locked" in str(e) and attempt < max_retries - 1:
+                    time.sleep(retry_delay * (attempt + 1))  # Exponential backoff
+                    continue
+                raise
+
+            except Exception:
+                try:
+                    conn.execute("ROLLBACK")
+                    conn.execute("PRAGMA busy_timeout=30000")
+                except Exception:
+                    pass
+                raise
+
+        # Should not reach here, but just in case
+        return True, None
+
+    def atomic_release_item(self, session_id: str, item_ref: str) -> bool:
+        """Atomically release an item from a session.
+
+        Uses BEGIN IMMEDIATE with retry logic for consistency with atomic_claim_item.
+        """
+        import time
+
+        max_retries = 3
+        retry_delay = 0.1
+
+        for attempt in range(max_retries):
+            conn = self._get_conn()
+            try:
+                conn.execute("PRAGMA busy_timeout=1000")
+                conn.execute("BEGIN IMMEDIATE")
+
+                cursor = conn.execute(
+                    "SELECT claimed_items FROM sessions WHERE id = ?",
+                    (session_id,),
+                )
+                row = cursor.fetchone()
+                if not row:
+                    conn.execute("ROLLBACK")
+                    conn.execute("PRAGMA busy_timeout=30000")
+                    return False
+
+                current_claims = row["claimed_items"].split(",") if row["claimed_items"] else []
+                if item_ref in current_claims:
+                    current_claims.remove(item_ref)
+                    conn.execute(
+                        "UPDATE sessions SET claimed_items = ? WHERE id = ?",
+                        (",".join(current_claims) if current_claims else None, session_id),
+                    )
+                    conn.execute("COMMIT")
+                    conn.execute("PRAGMA busy_timeout=30000")
+                    return True
+
+                conn.execute("ROLLBACK")
+                conn.execute("PRAGMA busy_timeout=30000")
+                return False
+
+            except sqlite3.OperationalError as e:
+                try:
+                    conn.execute("ROLLBACK")
+                except Exception:
+                    pass
+                try:
+                    conn.execute("PRAGMA busy_timeout=30000")
+                except Exception:
+                    pass
+
+                if "database is locked" in str(e) and attempt < max_retries - 1:
+                    time.sleep(retry_delay * (attempt + 1))
+                    continue
+                raise
+
+            except Exception:
+                try:
+                    conn.execute("ROLLBACK")
+                    conn.execute("PRAGMA busy_timeout=30000")
+                except Exception:
+                    pass
+                raise
+
+        return False
+
+    def get_item_owner(self, item_ref: str, stale_minutes: int = 30) -> str | None:
+        """Get the session that owns an item (if any active session)."""
+        cutoff = datetime.now(UTC).timestamp() - (stale_minutes * 60)
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT id, claimed_items FROM sessions
+                WHERE claimed_items LIKE ?
+                  AND datetime(last_heartbeat) > datetime(?, 'unixepoch')
+                """,
+                (f"%{item_ref}%", cutoff),
+            )
+            for row in cursor.fetchall():
+                claimed = row["claimed_items"].split(",") if row["claimed_items"] else []
+                if item_ref in claimed:
+                    return row["id"]
+        return None
+
+    def get_ingest_state(self, source: str) -> dict[str, Any] | None:
+        """Get ingestion state for a source."""
+        with self._get_conn() as conn:
+            cursor = conn.execute("SELECT * FROM ingest_state WHERE source = ?", (source,))
+            row = cursor.fetchone()
+            if row:
+                return {
+                    "source": row["source"],
+                    "last_processed": row["last_processed"],
+                    "last_id": row["last_id"],
+                    "metadata": row["metadata"],
+                }
+            return None
+
+    def set_ingest_state(
+        self, source: str, last_processed: str, last_id: str | None = None
+    ) -> None:
+        """Update ingestion state for a source."""
+        with self._get_conn() as conn:
+            conn.execute(
+                """
+                INSERT INTO ingest_state (source, last_processed, last_id)
+                VALUES (?, ?, ?)
+                ON CONFLICT(source) DO UPDATE SET
+                    last_processed = excluded.last_processed,
+                    last_id = excluded.last_id
+                """,
+                (source, last_processed, last_id),
+            )
+
+    def get_ingested_session_ids(self) -> set[str]:
+        """Get all source_file values for ingested OpenCode sessions."""
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                "SELECT DISTINCT source_file FROM memories WHERE source_file LIKE 'opencode:session:%'"
+            )
+            return {row["source_file"] for row in cursor.fetchall()}
+
+    def delete_memories_for_session(self, session_id: str) -> int:
+        """Delete all memories for a session (for re-ingestion)."""
+        source_file = f"opencode:session:{session_id}"
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                "DELETE FROM memories WHERE source_file = ?",
+                (source_file,),
+            )
+            return cursor.rowcount
+
+    def get_session_memory_count(self, session_id: str) -> int:
+        """Get the number of memories for a session."""
+        source_file = f"opencode:session:{session_id}"
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                "SELECT COUNT(*) FROM memories WHERE source_file = ?",
+                (source_file,),
+            )
+            return cursor.fetchone()[0]
+
+    def get_stale_entities(self, max_age_hours: int = 24, limit: int = 50) -> list[Entity]:
+        """Get entities that haven't been enriched or are stale (legacy method)."""
+        return self.get_entities_for_refresh(limit=limit)
+
+    def get_entities_for_refresh(self, limit: int = 50) -> list[Entity]:
+        """Get entities due for refresh based on tiered scheduling.
+
+        Refresh frequency based on activity (last_mentioned_at):
+        - Hot (mentioned in last 24h): refresh if not enriched in last 1 hour
+        - Warm (mentioned in last 7 days): refresh if not enriched in last 6 hours
+        - Cool (mentioned in last 30 days): refresh if not enriched in last 24 hours
+        - Cold (older or never mentioned): refresh if not enriched in last 7 days
+
+        Also includes entities that have never been enriched (no title/metadata).
+        """
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT *,
+                    CASE 
+                        WHEN last_mentioned_at > datetime('now', '-1 day') THEN 'hot'
+                        WHEN last_mentioned_at > datetime('now', '-7 days') THEN 'warm'
+                        WHEN last_mentioned_at > datetime('now', '-30 days') THEN 'cool'
+                        ELSE 'cold'
+                    END as heat_tier
+                FROM entities 
+                WHERE 
+                    -- Never enriched
+                    (title IS NULL OR metadata IS NULL OR last_enriched_at IS NULL)
+                    OR
+                    -- Hot: refresh hourly
+                    (last_mentioned_at > datetime('now', '-1 day') 
+                     AND (last_enriched_at IS NULL OR last_enriched_at < datetime('now', '-1 hour')))
+                    OR
+                    -- Warm: refresh every 6 hours
+                    (last_mentioned_at > datetime('now', '-7 days') 
+                     AND last_mentioned_at <= datetime('now', '-1 day')
+                     AND (last_enriched_at IS NULL OR last_enriched_at < datetime('now', '-6 hours')))
+                    OR
+                    -- Cool: refresh daily
+                    (last_mentioned_at > datetime('now', '-30 days') 
+                     AND last_mentioned_at <= datetime('now', '-7 days')
+                     AND (last_enriched_at IS NULL OR last_enriched_at < datetime('now', '-1 day')))
+                    OR
+                    -- Cold: refresh weekly
+                    ((last_mentioned_at IS NULL OR last_mentioned_at <= datetime('now', '-30 days'))
+                     AND (last_enriched_at IS NULL OR last_enriched_at < datetime('now', '-7 days')))
+                ORDER BY 
+                    -- Prioritize: never enriched, then hot, warm, cool, cold
+                    CASE 
+                        WHEN title IS NULL OR metadata IS NULL THEN 0
+                        WHEN last_mentioned_at > datetime('now', '-1 day') THEN 1
+                        WHEN last_mentioned_at > datetime('now', '-7 days') THEN 2
+                        WHEN last_mentioned_at > datetime('now', '-30 days') THEN 3
+                        ELSE 4
+                    END,
+                    last_enriched_at ASC NULLS FIRST
+                LIMIT ?
+                """,
+                (limit,),
+            )
+            entities = []
+            for row in cursor.fetchall():
+                metadata = {}
+                if row["metadata"]:
+                    try:
+                        metadata = json.loads(row["metadata"])
+                    except json.JSONDecodeError:
+                        pass
+                entities.append(
+                    Entity(
+                        id=row["id"],
+                        type=EntityType(row["type"]),
+                        ref=row["ref"],
+                        project=row["project"],
+                        title=row["title"],
+                        metadata=metadata,
+                        created_at=datetime.fromisoformat(row["created_at"]),
+                        updated_at=datetime.fromisoformat(row["updated_at"]),
+                    )
+                )
+            return entities
+
+    def update_entity_enriched(self, entity_id: int) -> None:
+        """Mark an entity as just enriched."""
+        with self._get_conn() as conn:
+            conn.execute(
+                "UPDATE entities SET last_enriched_at = ? WHERE id = ?",
+                (datetime.now(UTC).isoformat(), entity_id),
+            )
+
+    def bump_entity_mention(self, entity_id: int) -> None:
+        """Bump an entity to 'hot' status by updating last_mentioned_at."""
+        with self._get_conn() as conn:
+            conn.execute(
+                "UPDATE entities SET last_mentioned_at = ? WHERE id = ?",
+                (datetime.now(UTC).isoformat(), entity_id),
+            )
+
+    def archive_memory(self, memory_id: int, reason: str) -> bool:
+        """Archive a memory (move to archive table)."""
+        with self._get_conn() as conn:
+            cursor = conn.execute("SELECT * FROM memories WHERE id = ?", (memory_id,))
+            row = cursor.fetchone()
+            if not row:
+                return False
+
+            conn.execute(
+                """
+                INSERT INTO archived_memories 
+                (id, source_file, source_line, category, content, what, why, learned,
+                 created_at, expires_at, resolved_at, archived_at, archive_reason)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    row["id"],
+                    row["source_file"],
+                    row["source_line"],
+                    row["category"],
+                    row["content"],
+                    row["what"],
+                    row["why"],
+                    row["learned"],
+                    row["created_at"],
+                    row["expires_at"],
+                    row["resolved_at"],
+                    datetime.now(UTC).isoformat(),
+                    reason,
+                ),
+            )
+
+            conn.execute("DELETE FROM memories WHERE id = ?", (memory_id,))
+            return True
+
+    def archive_expired_memories(self) -> int:
+        """Archive all memories past their expiration date."""
+        now = datetime.now(UTC).isoformat()
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT id FROM memories 
+                WHERE expires_at IS NOT NULL AND expires_at < ?
+                """,
+                (now,),
+            )
+            expired_ids = [row["id"] for row in cursor.fetchall()]
+
+        archived = 0
+        for memory_id in expired_ids:
+            if self.archive_memory(memory_id, "expired"):
+                archived += 1
+        return archived
+
+    def archive_old_resolved_blockers(self, days_old: int = 90) -> int:
+        """Archive blockers that were resolved more than N days ago.
+
+        Note: This is for storage management only. Resolved blockers are
+        already excluded from boot context. Use a conservative threshold.
+        """
+        cutoff = (datetime.now(UTC) - timedelta(days=days_old)).isoformat()
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT id FROM memories 
+                WHERE category = 'blocker' 
+                AND resolved_at IS NOT NULL 
+                AND resolved_at < ?
+                """,
+                (cutoff,),
+            )
+            old_ids = [row["id"] for row in cursor.fetchall()]
+
+        archived = 0
+        for memory_id in old_ids:
+            if self.archive_memory(memory_id, "old_resolved_blocker"):
+                archived += 1
+        return archived
+
+    def archive_old_conversations(self, days_old: int = 180) -> int:
+        """Archive conversation summaries older than N days.
+
+        Note: This is for storage management on very old data (6+ months).
+        Archived conversations remain searchable via search_archived().
+        """
+        cutoff = (datetime.now(UTC) - timedelta(days=days_old)).isoformat()
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT id FROM memories 
+                WHERE category = 'conversation' 
+                AND created_at < ?
+                """,
+                (cutoff,),
+            )
+            old_ids = [row["id"] for row in cursor.fetchall()]
+
+        archived = 0
+        for memory_id in old_ids:
+            if self.archive_memory(memory_id, "old_conversation"):
+                archived += 1
+        return archived
+
+    def resolve_blockers_for_entity(self, entity_ref: str) -> int:
+        """Mark all blockers mentioning an entity as resolved."""
+        now = datetime.now(UTC).isoformat()
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                UPDATE memories 
+                SET resolved_at = ?
+                WHERE category = 'blocker' 
+                AND resolved_at IS NULL
+                AND (content LIKE ? OR content LIKE ?)
+                """,
+                (now, f"%{entity_ref}%", f"%{entity_ref.lstrip('!#&@')}%"),
+            )
+            return cursor.rowcount
+
+    def get_archived_memories(self, limit: int = 50) -> list[dict]:
+        """Get archived memories for audit purposes."""
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT * FROM archived_memories 
+                ORDER BY archived_at DESC 
+                LIMIT ?
+                """,
+                (limit,),
+            )
+            return [dict(row) for row in cursor.fetchall()]
+
+    def get_cleanup_stats(self) -> dict:
+        """Get statistics about memory cleanup candidates."""
+        with self._get_conn() as conn:
+            stats = {}
+
+            cursor = conn.execute(
+                "SELECT COUNT(*) FROM memories WHERE expires_at IS NOT NULL AND expires_at < datetime('now')"
+            )
+            stats["expired"] = cursor.fetchone()[0]
+
+            cursor = conn.execute(
+                "SELECT COUNT(*) FROM memories WHERE category = 'blocker' AND resolved_at IS NOT NULL"
+            )
+            stats["resolved_blockers"] = cursor.fetchone()[0]
+
+            cursor = conn.execute(
+                "SELECT COUNT(*) FROM memories WHERE category = 'conversation' AND created_at < datetime('now', '-90 days')"
+            )
+            stats["old_conversations"] = cursor.fetchone()[0]
+
+            cursor = conn.execute("SELECT COUNT(*) FROM archived_memories")
+            stats["archived_total"] = cursor.fetchone()[0]
+
+            return stats
+
+    # ==================== Memory Links ====================
+
+    def insert_link(self, link: MemoryLink) -> int | None:
+        """Insert a memory link. Returns link ID or None if duplicate."""
+        with self._get_conn() as conn:
+            try:
+                cursor = conn.execute(
+                    """
+                    INSERT INTO memory_links 
+                    (source_memory_id, target_memory_id, link_type, strength, reason, created_at)
+                    VALUES (?, ?, ?, ?, ?, ?)
+                    RETURNING id
+                    """,
+                    (
+                        link.source_memory_id,
+                        link.target_memory_id,
+                        link.link_type.value,
+                        link.strength,
+                        link.reason,
+                        link.created_at.isoformat(),
+                    ),
+                )
+                row = cursor.fetchone()
+                return int(row[0]) if row else None
+            except sqlite3.IntegrityError:
+                return None
+
+    def get_links_for_memory(self, memory_id: int, as_source: bool = True) -> list[MemoryLink]:
+        """Get all links where memory is source (outgoing) or target (incoming)."""
+        with self._get_conn() as conn:
+            if as_source:
+                cursor = conn.execute(
+                    "SELECT * FROM memory_links WHERE source_memory_id = ?",
+                    (memory_id,),
+                )
+            else:
+                cursor = conn.execute(
+                    "SELECT * FROM memory_links WHERE target_memory_id = ?",
+                    (memory_id,),
+                )
+            return [self._row_to_link(row) for row in cursor.fetchall()]
+
+    def get_all_links_for_memory(self, memory_id: int) -> list[MemoryLink]:
+        """Get all links (both directions) for a memory."""
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT * FROM memory_links 
+                WHERE source_memory_id = ? OR target_memory_id = ?
+                """,
+                (memory_id, memory_id),
+            )
+            return [self._row_to_link(row) for row in cursor.fetchall()]
+
+    def get_linked_memory_ids(
+        self, memory_id: int, link_types: list[LinkType] | None = None
+    ) -> list[int]:
+        """Get IDs of memories linked to this one (both directions)."""
+        with self._get_conn() as conn:
+            if link_types:
+                type_placeholders = ",".join("?" * len(link_types))
+                type_values = [lt.value for lt in link_types]
+                cursor = conn.execute(
+                    f"""
+                    SELECT DISTINCT 
+                        CASE 
+                            WHEN source_memory_id = ? THEN target_memory_id 
+                            ELSE source_memory_id 
+                        END as linked_id
+                    FROM memory_links 
+                    WHERE (source_memory_id = ? OR target_memory_id = ?)
+                      AND link_type IN ({type_placeholders})
+                    """,
+                    [memory_id, memory_id, memory_id] + type_values,
+                )
+            else:
+                cursor = conn.execute(
+                    """
+                    SELECT DISTINCT 
+                        CASE 
+                            WHEN source_memory_id = ? THEN target_memory_id 
+                            ELSE source_memory_id 
+                        END as linked_id
+                    FROM memory_links 
+                    WHERE source_memory_id = ? OR target_memory_id = ?
+                    """,
+                    (memory_id, memory_id, memory_id),
+                )
+            return [row["linked_id"] for row in cursor.fetchall()]
+
+    def get_unlinked_memories(self, limit: int = 100) -> list[Memory]:
+        """Get memories that have no links yet (for background linking).
+
+        Prioritizes high-value categories (directive, procedure, fact, decision)
+        over conversations which are numerous but lower value for linking.
+        """
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT m.* FROM memories m
+                LEFT JOIN memory_links ml_src ON m.id = ml_src.source_memory_id
+                LEFT JOIN memory_links ml_tgt ON m.id = ml_tgt.target_memory_id
+                WHERE ml_src.id IS NULL AND ml_tgt.id IS NULL
+                  AND m.id NOT IN (SELECT id FROM archived_memories)
+                ORDER BY 
+                  CASE m.category 
+                    WHEN 'directive' THEN 1
+                    WHEN 'plan' THEN 2
+                    WHEN 'procedure' THEN 3
+                    WHEN 'fact' THEN 4
+                    WHEN 'decision' THEN 5
+                    WHEN 'blocker' THEN 6
+                    WHEN 'event' THEN 7
+                    WHEN 'conversation' THEN 8
+                    ELSE 9
+                  END,
+                  m.created_at DESC
+                LIMIT ?
+                """,
+                (limit,),
+            )
+            return [self._row_to_memory(row) for row in cursor.fetchall()]
+
+    def get_memories_needing_links(self, since_hours: int = 24, limit: int = 50) -> list[Memory]:
+        """Get recent memories that may need linking (created recently, few links)."""
+        cutoff = (datetime.now(UTC) - timedelta(hours=since_hours)).isoformat()
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT m.*, COUNT(ml.id) as link_count
+                FROM memories m
+                LEFT JOIN memory_links ml ON m.id = ml.source_memory_id OR m.id = ml.target_memory_id
+                WHERE m.created_at > ?
+                  AND m.id NOT IN (SELECT id FROM archived_memories)
+                GROUP BY m.id
+                HAVING link_count < 3
+                ORDER BY m.created_at DESC
+                LIMIT ?
+                """,
+                (cutoff, limit),
+            )
+            return [self._row_to_memory(row) for row in cursor.fetchall()]
+
+    def link_exists(self, source_id: int, target_id: int, link_type: LinkType) -> bool:
+        """Check if a specific link already exists."""
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT 1 FROM memory_links 
+                WHERE source_memory_id = ? AND target_memory_id = ? AND link_type = ?
+                """,
+                (source_id, target_id, link_type.value),
+            )
+            return cursor.fetchone() is not None
+
+    def any_link_exists(self, source_id: int, target_id: int) -> bool:
+        """Check if any link exists between two memories (in either direction)."""
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """
+                SELECT 1 FROM memory_links 
+                WHERE (source_memory_id = ? AND target_memory_id = ?)
+                   OR (source_memory_id = ? AND target_memory_id = ?)
+                """,
+                (source_id, target_id, target_id, source_id),
+            )
+            return cursor.fetchone() is not None
+
+    def delete_link(self, link_id: int) -> bool:
+        """Delete a memory link."""
+        with self._get_conn() as conn:
+            cursor = conn.execute("DELETE FROM memory_links WHERE id = ?", (link_id,))
+            return cursor.rowcount > 0
+
+    def get_link_stats(self) -> dict:
+        """Get statistics about memory links."""
+        with self._get_conn() as conn:
+            stats: dict[str, Any] = {}
+
+            cursor = conn.execute("SELECT COUNT(*) FROM memory_links")
+            stats["total_links"] = cursor.fetchone()[0]
+
+            cursor = conn.execute(
+                "SELECT link_type, COUNT(*) as cnt FROM memory_links GROUP BY link_type"
+            )
+            stats["by_type"] = {row["link_type"]: row["cnt"] for row in cursor.fetchall()}
+
+            cursor = conn.execute(
+                """
+                SELECT COUNT(DISTINCT m.id) as linked_count
+                FROM memories m
+                INNER JOIN memory_links ml ON m.id = ml.source_memory_id OR m.id = ml.target_memory_id
+                """
+            )
+            stats["memories_with_links"] = cursor.fetchone()[0]
+
+            cursor = conn.execute(
+                "SELECT COUNT(*) FROM memories WHERE id NOT IN (SELECT id FROM archived_memories)"
+            )
+            stats["total_memories"] = cursor.fetchone()[0]
+
+            return stats
+
+    def get_consolidation_stats(self, project: str | None, days_stale: int) -> dict[str, Any]:
+        """Get consolidation stats using efficient SQL queries."""
+        stale_threshold = (datetime.now(UTC) - timedelta(days=days_stale)).isoformat()
+
+        with self._get_conn() as conn:
+            # Total count
+            if project:
+                cursor = conn.execute(
+                    """SELECT COUNT(*) FROM memories 
+                       WHERE project = ? AND id NOT IN (SELECT id FROM archived_memories)""",
+                    (project,),
+                )
+            else:
+                cursor = conn.execute(
+                    "SELECT COUNT(*) FROM memories WHERE id NOT IN (SELECT id FROM archived_memories)"
+                )
+            total = cursor.fetchone()[0]
+
+            # By category
+            if project:
+                cursor = conn.execute(
+                    """SELECT category, COUNT(*) FROM memories 
+                       WHERE project = ? AND id NOT IN (SELECT id FROM archived_memories)
+                       GROUP BY category""",
+                    (project,),
+                )
+            else:
+                cursor = conn.execute(
+                    """SELECT category, COUNT(*) FROM memories 
+                       WHERE id NOT IN (SELECT id FROM archived_memories)
+                       GROUP BY category"""
+                )
+            by_category = {row[0]: row[1] for row in cursor.fetchall()}
+
+            # Stale records (facts/procedures older than threshold)
+            if project:
+                cursor = conn.execute(
+                    """SELECT id, category, content, created_at FROM memories 
+                       WHERE project = ? 
+                         AND category IN ('fact', 'procedure')
+                         AND created_at < ?
+                         AND id NOT IN (SELECT id FROM archived_memories)
+                       ORDER BY created_at ASC
+                       LIMIT 50""",
+                    (project, stale_threshold),
+                )
+            else:
+                cursor = conn.execute(
+                    """SELECT id, category, content, created_at FROM memories 
+                       WHERE category IN ('fact', 'procedure')
+                         AND created_at < ?
+                         AND id NOT IN (SELECT id FROM archived_memories)
+                       ORDER BY created_at ASC
+                       LIMIT 50""",
+                    (stale_threshold,),
+                )
+            stale_records = [
+                {
+                    "id": row["id"],
+                    "category": row["category"],
+                    "content": row["content"][:100] + "..."
+                    if len(row["content"]) > 100
+                    else row["content"],
+                    "age": _format_age_from_iso(row["created_at"]),
+                }
+                for row in cursor.fetchall()
+            ]
+
+            return {
+                "total": total,
+                "by_category": by_category,
+                "stale_records": stale_records,
+            }
+
+    def get_recent_consolidation_report(self, max_age_hours: int = 24) -> Memory | None:
+        """Get the most recent consolidation report if one exists within max_age."""
+        cutoff = (datetime.now(UTC) - timedelta(hours=max_age_hours)).isoformat()
+        with self._get_conn() as conn:
+            cursor = conn.execute(
+                """SELECT * FROM memories 
+                   WHERE what = 'Memory consolidation report'
+                     AND created_at > ?
+                     AND id NOT IN (SELECT id FROM archived_memories)
+                   ORDER BY created_at DESC
+                   LIMIT 1""",
+                (cutoff,),
+            )
+            row = cursor.fetchone()
+            return self._row_to_memory(row) if row else None
+
+    def get_recent_memories_for_dedup(
+        self, project: str | None, limit: int, days: int
+    ) -> list[Memory]:
+        """Get recent memories for duplicate detection."""
+        cutoff = (datetime.now(UTC) - timedelta(days=days)).isoformat()
+        with self._get_conn() as conn:
+            if project:
+                cursor = conn.execute(
+                    """SELECT * FROM memories 
+                       WHERE project = ? AND created_at > ?
+                         AND id NOT IN (SELECT id FROM archived_memories)
+                       ORDER BY created_at DESC
+                       LIMIT ?""",
+                    (project, cutoff, limit),
+                )
+            else:
+                cursor = conn.execute(
+                    """SELECT * FROM memories 
+                       WHERE created_at > ?
+                         AND id NOT IN (SELECT id FROM archived_memories)
+                       ORDER BY created_at DESC
+                       LIMIT ?""",
+                    (cutoff, limit),
+                )
+            return [self._row_to_memory(row) for row in cursor.fetchall()]
+
+    def _row_to_link(self, row: sqlite3.Row) -> MemoryLink:
+        """Convert a database row to a MemoryLink object."""
+        return MemoryLink(
+            id=row["id"],
+            source_memory_id=row["source_memory_id"],
+            target_memory_id=row["target_memory_id"],
+            link_type=LinkType(row["link_type"]),
+            strength=row["strength"],
+            reason=row["reason"],
+            created_at=datetime.fromisoformat(row["created_at"]),
+        )