agent-memory-os 0.2.4__tar.gz → 0.3.0__tar.gz

{agent_memory_os-0.2.4 → agent_memory_os-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-memory-os
-Version: 0.2.4
+Version: 0.3.0
 Summary: Local-first, MCP-native memory engine for AI agents with RAM cache and context-budgeted recall.
 Author: Bastet Agent Team
 License-Expression: Apache-2.0
@@ -140,21 +140,33 @@ AgentMemoryOS uses **two storage layers with strictly different authority**:
   ACL/expiry hard gates before its content can be used, and the index can be
   dropped and rebuilt at any time without touching the truth store.
 
-To activate semantic recall, supply an embedding function and wire the
-provider in:
+Semantic recall works out of the box:
 
 ```python
-from agent_memory_os.providers.turbovec import TurbovecSemanticCandidateProvider
-
-provider = TurbovecSemanticCandidateProvider.from_vectors(
-    vectors=embeddings,                      # one row per memory, any embedder
-    external_id_by_memory_id=id_mapping,     # stable memory_id -> uint64
-    embed_query=embed,                       # str -> vector, same embedder
-)
-client = MemoryClient(home="~/.agent-memory", candidate_providers=[provider])
+client = MemoryClient(home="~/.agent-memory", semantic="auto")
 ```
 
-`agent-memory doctor` confirms the turbovec backend is importable.
+`semantic="auto"` wires in a self-syncing turbovec index over a built-in
+deterministic hashing embedder (no model downloads; typo- and
+morphology-tolerant lexical vectors). The index rebuilds itself whenever the
+memories table changes and degrades silently to lexical + resonance recall
+when the backend isn't installed. For deeper semantics, plug any embedding
+model into `TurbovecSemanticCandidateProvider.from_vectors(...)` with your
+own `embed_query`. `agent-memory doctor` confirms the backend is importable.
+
+## Memory lifecycle & retention
+
+```bash
+agent-memory retention               # archive expired + memories idle 4+ half-lives
+agent-memory retention --half-lives 0   # expired only
+agent-memory check                   # SQLite + FTS + link-graph integrity
+```
+
+Archived memories leave recall entirely but stay restorable (Web UI → Tools →
+Retention & archive, or `POST /api/archive/{id}/restore`). Pinned and
+authority-track memories are never archived by decay. Databases self-migrate
+through a versioned, forward-only migration table (`agent-memory check`
+reports the schema version).
 
 ## Backup & restore
 

{agent_memory_os-0.2.4 → agent_memory_os-0.3.0}/README.md

@@ -109,21 +109,33 @@ AgentMemoryOS uses **two storage layers with strictly different authority**:
   ACL/expiry hard gates before its content can be used, and the index can be
   dropped and rebuilt at any time without touching the truth store.
 
-To activate semantic recall, supply an embedding function and wire the
-provider in:
+Semantic recall works out of the box:
 
 ```python
-from agent_memory_os.providers.turbovec import TurbovecSemanticCandidateProvider
-
-provider = TurbovecSemanticCandidateProvider.from_vectors(
-    vectors=embeddings,                      # one row per memory, any embedder
-    external_id_by_memory_id=id_mapping,     # stable memory_id -> uint64
-    embed_query=embed,                       # str -> vector, same embedder
-)
-client = MemoryClient(home="~/.agent-memory", candidate_providers=[provider])
+client = MemoryClient(home="~/.agent-memory", semantic="auto")
 ```
 
-`agent-memory doctor` confirms the turbovec backend is importable.
+`semantic="auto"` wires in a self-syncing turbovec index over a built-in
+deterministic hashing embedder (no model downloads; typo- and
+morphology-tolerant lexical vectors). The index rebuilds itself whenever the
+memories table changes and degrades silently to lexical + resonance recall
+when the backend isn't installed. For deeper semantics, plug any embedding
+model into `TurbovecSemanticCandidateProvider.from_vectors(...)` with your
+own `embed_query`. `agent-memory doctor` confirms the backend is importable.
+
+## Memory lifecycle & retention
+
+```bash
+agent-memory retention               # archive expired + memories idle 4+ half-lives
+agent-memory retention --half-lives 0   # expired only
+agent-memory check                   # SQLite + FTS + link-graph integrity
+```
+
+Archived memories leave recall entirely but stay restorable (Web UI → Tools →
+Retention & archive, or `POST /api/archive/{id}/restore`). Pinned and
+authority-track memories are never archived by decay. Databases self-migrate
+through a versioned, forward-only migration table (`agent-memory check`
+reports the schema version).
 
 ## Backup & restore
 

{agent_memory_os-0.2.4 → agent_memory_os-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-memory-os"
-version = "0.2.4"
+version = "0.3.0"
 description = "Local-first, MCP-native memory engine for AI agents with RAM cache and context-budgeted recall."
 readme = "README.md"
 requires-python = ">=3.11"

{agent_memory_os-0.2.4 → agent_memory_os-0.3.0}/src/agent_memory_os/cli.py

@@ -67,6 +67,14 @@ def build_parser() -> argparse.ArgumentParser:
     restore = sub.add_parser("restore", help="Restore the memory database from a backup file")
     restore.add_argument("src", help="Backup .db file to restore from")
     restore.add_argument("--force", action="store_true", help="Overwrite an existing database")
+
+    sub.add_parser("check", help="Run database integrity and invariant checks")
+
+    retention = sub.add_parser("retention", help="Archive expired and deeply-decayed memories")
+    retention.add_argument(
+        "--half-lives", type=float, default=None,
+        help="Also archive unpinned memories idle for N decay half-lives (default 4; 0 = expired only)",
+    )
     return p
 
 
@@ -229,6 +237,17 @@ def main(argv: list[str] | None = None) -> int:
 
     client = MemoryClient(home=args.home)
     try:
+        if args.command == "check":
+            report = client.integrity_check()
+            print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True))
+            return 0 if report["ok"] else 1
+        if args.command == "retention":
+            if args.half_lives is None:
+                result = client.run_retention()
+            else:
+                result = client.run_retention(decayed_half_lives=args.half_lives or None)
+            print(json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True))
+            return 0
         if args.command == "golden-recall":
             cases = load_golden_query_cases(args.cases)
             report = evaluate_golden_queries(

{agent_memory_os-0.2.4 → agent_memory_os-0.3.0}/src/agent_memory_os/client.py

@@ -9,7 +9,7 @@ import json
 from .candidates import CandidateProvider
 from .cache import LRUCache
 from .context_pack import ContextPackReport, build_context_pack, build_context_pack_report
-from .db import MemoryStore
+from .db import MemoryStore, RETENTION_MIN_HALF_LIVES
 from .schema import MemoryLink, MemoryRecord, RecallProfile, SearchResult
 
 class MemoryClient:
@@ -22,6 +22,7 @@ class MemoryClient:
         resonance_hops: int = 1,
         profile: RecallProfile | None = None,
         check_same_thread: bool = True,
+        semantic: str | None = None,
     ):
         home_path = Path(home or os.getenv("AGENT_MEMORY_HOME", "~/.agent-memory")).expanduser()
         self.home = home_path
@@ -31,6 +32,20 @@ class MemoryClient:
             resonance_hops=resonance_hops,
             check_same_thread=check_same_thread,
         )
+        self.semantic_enabled = False
+        if semantic == "auto":
+            # Out-of-the-box semantic recall: hashing embedder + self-syncing
+            # turbovec index. Degrades silently when the backend isn't
+            # installed — lexical/resonance recall still works.
+            from .providers.turbovec import semantic_backend_available
+
+            if semantic_backend_available():
+                from .embedding import AutoSemanticIndex
+
+                self.store.candidate_providers.append(AutoSemanticIndex(self.store))
+                self.semantic_enabled = True
+        elif semantic is not None:
+            raise ValueError('semantic must be "auto" or None')
         self.profile = profile
         self.cache: LRUCache[tuple, object] = LRUCache(max_items=cache_items)
         self._profile_cache: dict[str, RecallProfile | None] = {}
@@ -64,6 +79,28 @@ class MemoryClient:
         self.cache.clear()
         return result
 
+    def run_retention(
+        self, *, decayed_half_lives: float | None = RETENTION_MIN_HALF_LIVES
+    ) -> dict[str, int]:
+        """Archive expired (and optionally deeply-decayed) memories.
+
+        `decayed_half_lives=None` (or 0) archives expired memories only.
+        """
+        result = self.store.run_retention(decayed_half_lives=decayed_half_lives)
+        self.cache.clear()
+        return result
+
+    def list_archived(self, *, limit: int = 20, offset: int = 0) -> list[dict[str, object]]:
+        return self.store.list_archived(limit=limit, offset=offset)
+
+    def restore_archived(self, memory_id: str) -> MemoryRecord:
+        restored = self.store.restore_archived(memory_id)
+        self.cache.clear()
+        return restored
+
+    def integrity_check(self) -> dict[str, object]:
+        return self.store.integrity_check()
+
     def dashboard_stats(self) -> dict[str, object]:
         return self.store.dashboard_stats() | {"cache_items": len(self.cache)}
 

{agent_memory_os-0.2.4 → agent_memory_os-0.3.0}/src/agent_memory_os/db.py

@@ -99,6 +99,73 @@ AUTO_LINK_LIMIT = 5
 CONSOLIDATION_MIN_CLUSTER_WEIGHT = 0.6
 CONSOLIDATION_MIN_ACTIVATIONS = 3
 CONSOLIDATION_MIN_CLUSTER_SIZE = 3
+RETENTION_MIN_HALF_LIVES = 4.0
+
+
+def _migration_decay_columns(conn: sqlite3.Connection) -> None:
+    existing = {row["name"] for row in conn.execute("PRAGMA table_info(memories)")}
+    columns = {
+        "decay_policy": "TEXT NOT NULL DEFAULT 'exponential'",
+        "decay_half_life_days": "REAL NOT NULL DEFAULT 30.0",
+        "last_accessed_at": "TEXT",
+        "access_count": "INTEGER NOT NULL DEFAULT 0",
+        "pinned": "INTEGER NOT NULL DEFAULT 0",
+    }
+    for name, definition in columns.items():
+        if name not in existing:
+            conn.execute(f"ALTER TABLE memories ADD COLUMN {name} {definition}")
+
+
+def _migration_fix_fts_triggers(conn: sqlite3.Connection) -> None:
+    # Legacy AFTER UPDATE/DELETE triggers used the FTS5 'delete' command,
+    # which is invalid on regular FTS5 tables and raised 'SQL logic error'
+    # on every update_content()/delete().
+    rows = conn.execute(
+        "SELECT name, sql FROM sqlite_master WHERE type = 'trigger' AND name IN ('memories_ad', 'memories_au')"
+    ).fetchall()
+    broken = [row["name"] for row in rows if "'delete'" in (row["sql"] or "")]
+    if not broken:
+        return
+    for name in broken:
+        conn.execute(f"DROP TRIGGER IF EXISTS {name}")
+    conn.executescript(SCHEMA)
+
+
+def _migration_archive_table(conn: sqlite3.Connection) -> None:
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS memories_archive (
+          id TEXT PRIMARY KEY,
+          owner TEXT NOT NULL,
+          scope TEXT NOT NULL,
+          type TEXT NOT NULL,
+          content TEXT NOT NULL,
+          summary TEXT NOT NULL,
+          tags TEXT NOT NULL DEFAULT '[]',
+          visibility TEXT NOT NULL DEFAULT '[]',
+          source TEXT NOT NULL DEFAULT '{}',
+          confidence REAL NOT NULL DEFAULT 0.8,
+          importance REAL NOT NULL DEFAULT 0.5,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          expires_at TEXT,
+          decay_policy TEXT NOT NULL DEFAULT 'exponential',
+          decay_half_life_days REAL NOT NULL DEFAULT 30.0,
+          last_accessed_at TEXT,
+          access_count INTEGER NOT NULL DEFAULT 0,
+          pinned INTEGER NOT NULL DEFAULT 0,
+          archived_at TEXT NOT NULL,
+          archive_reason TEXT NOT NULL
+        )
+        """
+    )
+
+
+MIGRATIONS: list[tuple[int, str, object]] = [
+    (1, "decay and reinforcement columns", _migration_decay_columns),
+    (2, "repair FTS update/delete triggers", _migration_fix_fts_triggers),
+    (3, "cold archive table", _migration_archive_table),
+]
 
 
 class MemoryStore:
@@ -128,43 +195,70 @@ class MemoryStore:
         self.conn.execute("PRAGMA busy_timeout=5000")
         self.conn.execute("PRAGMA journal_mode=WAL")
         self.conn.executescript(SCHEMA)
-        self._ensure_decay_columns()
-        self._ensure_valid_fts_triggers()
+        self._run_migrations()
         self.conn.commit()
 
     def close(self) -> None:
         self.conn.close()
 
-    def _ensure_decay_columns(self) -> None:
-        existing = {row["name"] for row in self.conn.execute("PRAGMA table_info(memories)")}
-        columns = {
-            "decay_policy": "TEXT NOT NULL DEFAULT 'exponential'",
-            "decay_half_life_days": "REAL NOT NULL DEFAULT 30.0",
-            "last_accessed_at": "TEXT",
-            "access_count": "INTEGER NOT NULL DEFAULT 0",
-            "pinned": "INTEGER NOT NULL DEFAULT 0",
+    # ------------------------------------------------------------------ #
+    # Schema migrations: forward-only, versioned, recorded per database.
+    # Each migration must be idempotent (it may run once against databases
+    # created before the migrations table existed).
+    # ------------------------------------------------------------------ #
+
+    def _run_migrations(self) -> None:
+        self.conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS schema_migrations (
+              version INTEGER PRIMARY KEY,
+              description TEXT NOT NULL,
+              applied_at TEXT NOT NULL
+            )
+            """
+        )
+        applied = {
+            row["version"] for row in self.conn.execute("SELECT version FROM schema_migrations")
         }
-        for name, definition in columns.items():
-            if name not in existing:
-                self.conn.execute(f"ALTER TABLE memories ADD COLUMN {name} {definition}")
+        for version, description, migrate in MIGRATIONS:
+            if version in applied:
+                continue
+            migrate(self.conn)
+            self.conn.execute(
+                "INSERT INTO schema_migrations(version, description, applied_at) VALUES (?, ?, ?)",
+                (version, description, utc_now()),
+            )
+
+    def schema_version(self) -> int:
+        row = self.conn.execute("SELECT MAX(version) FROM schema_migrations").fetchone()
+        return int(row[0] or 0)
 
-    def _ensure_valid_fts_triggers(self) -> None:
-        """Replace legacy FTS triggers that used the FTS5 'delete' command.
+    def integrity_check(self) -> dict[str, object]:
+        """Verify the database and the store's own invariants.
 
-        The 'delete' command is only valid for external-content/contentless
-        FTS5 tables; on this regular FTS5 table it raises 'SQL logic error' on
-        every UPDATE/DELETE. Databases created before the fix keep the broken
-        triggers because SCHEMA uses CREATE TRIGGER IF NOT EXISTS.
+        Returns per-check results; `ok` is the conjunction. Read-only.
         """
-        rows = self.conn.execute(
-            "SELECT name, sql FROM sqlite_master WHERE type = 'trigger' AND name IN ('memories_ad', 'memories_au')"
-        ).fetchall()
-        broken = [row["name"] for row in rows if "'delete'" in (row["sql"] or "")]
-        if not broken:
-            return
-        for name in broken:
-            self.conn.execute(f"DROP TRIGGER IF EXISTS {name}")
-        self.conn.executescript(SCHEMA)
+        checks: dict[str, object] = {}
+        pragma = self.conn.execute("PRAGMA integrity_check").fetchone()[0]
+        checks["sqlite_integrity"] = pragma == "ok"
+        total = self.conn.execute("SELECT COUNT(*) FROM memories").fetchone()[0]
+        indexed = self.conn.execute("SELECT COUNT(*) FROM memories_fts").fetchone()[0]
+        checks["fts_in_sync"] = indexed == total
+        checks["fts_rows"] = {"memories": int(total), "indexed": int(indexed)}
+        orphan_edges = self.conn.execute(
+            """
+            SELECT COUNT(*) FROM memory_links l
+            WHERE NOT EXISTS (SELECT 1 FROM memories m WHERE m.id = l.src_id)
+               OR NOT EXISTS (SELECT 1 FROM memories m WHERE m.id = l.dst_id)
+            """
+        ).fetchone()[0]
+        checks["orphan_links"] = int(orphan_edges)
+        checks["links_valid"] = orphan_edges == 0
+        checks["schema_version"] = self.schema_version()
+        checks["ok"] = bool(
+            checks["sqlite_integrity"] and checks["fts_in_sync"] and checks["links_valid"]
+        )
+        return checks
 
     def add(self, record: MemoryRecord) -> MemoryRecord:
         record.summary = record.normalized_summary()
@@ -422,6 +516,25 @@ class MemoryStore:
         ).fetchall()
         return [self._row_to_record(row) for row in rows]
 
+    def semantic_corpus(self) -> list[tuple[int, str, str]]:
+        """(rowid, memory_id, embeddable text) for every memory — the auto
+        semantic indexer's rebuild source. rowid doubles as the uint64
+        external id; full rebuilds make rowid reuse after deletes harmless."""
+        rows = self.conn.execute(
+            "SELECT rowid AS rid, id, content, summary, tags FROM memories"
+        ).fetchall()
+        return [
+            (int(row["rid"]), row["id"], f"{row['content']}\n{row['summary']}\n{row['tags']}")
+            for row in rows
+        ]
+
+    def semantic_signature(self) -> tuple:
+        """Cheap change signature used to decide when the auto index rebuilds."""
+        row = self.conn.execute(
+            "SELECT COUNT(*), COALESCE(MAX(rowid), 0), COALESCE(MAX(updated_at), '') FROM memories"
+        ).fetchone()
+        return (int(row[0]), int(row[1]), row[2])
+
     def graph_snapshot(
         self,
         *,
@@ -640,6 +753,108 @@ class MemoryStore:
         }
         return [memory_id for memory_id in ordered if memory_id in visible]
 
+    _MEMORY_COLUMNS = (
+        "id, owner, scope, type, content, summary, tags, visibility, source, "
+        "confidence, importance, created_at, updated_at, expires_at, "
+        "decay_policy, decay_half_life_days, last_accessed_at, access_count, pinned"
+    )
+
+    def run_retention(
+        self, *, decayed_half_lives: float | None = RETENTION_MIN_HALF_LIVES
+    ) -> dict[str, int]:
+        """Move expired (and optionally deeply-decayed) memories to cold archive.
+
+        Archived memories leave active recall entirely but stay restorable.
+        Pinned and authority-track records are never archived by decay; only a
+        hard expiry can retire them.
+        """
+        now = utc_now()
+        expired = self._archive_where(
+            "expires_at IS NOT NULL AND expires_at <= ?", [now], reason="expired"
+        )
+        decayed = 0
+        if decayed_half_lives and decayed_half_lives > 0:
+            decayed = self._archive_where(
+                """
+                pinned = 0 AND decay_policy != 'none'
+                AND NOT (COALESCE(json_extract(source, '$.permanence'), 0) = 1
+                         AND COALESCE(json_extract(source, '$.weight'), 0) >= 10)
+                AND (julianday(?) - julianday(COALESCE(last_accessed_at, updated_at)))
+                    > (? * decay_half_life_days)
+                """,
+                [now, float(decayed_half_lives)],
+                reason="decayed",
+            )
+        return {"archived_expired": expired, "archived_decayed": decayed}
+
+    def _archive_where(self, where_sql: str, params: list[object], *, reason: str) -> int:
+        rows = self.conn.execute(
+            f"SELECT id FROM memories WHERE {where_sql}", params
+        ).fetchall()
+        ids = [row["id"] for row in rows]
+        if not ids:
+            return 0
+        now = utc_now()
+        placeholders = ",".join("?" for _ in ids)
+        self.conn.execute(
+            f"""
+            INSERT OR REPLACE INTO memories_archive
+            SELECT {self._MEMORY_COLUMNS}, ?, ? FROM memories WHERE id IN ({placeholders})
+            """,
+            [now, reason, *ids],
+        )
+        self.conn.execute(
+            f"DELETE FROM memory_links WHERE src_id IN ({placeholders}) OR dst_id IN ({placeholders})",
+            [*ids, *ids],
+        )
+        self.conn.execute(f"DELETE FROM memories WHERE id IN ({placeholders})", ids)
+        self.conn.commit()
+        return len(ids)
+
+    def list_archived(self, *, limit: int = 20, offset: int = 0) -> list[dict[str, object]]:
+        rows = self.conn.execute(
+            "SELECT * FROM memories_archive ORDER BY archived_at DESC, rowid DESC LIMIT ? OFFSET ?",
+            (max(1, limit), max(0, offset)),
+        ).fetchall()
+        return [
+            {
+                "id": row["id"], "owner": row["owner"], "scope": row["scope"],
+                "type": row["type"], "content": row["content"], "summary": row["summary"],
+                "archived_at": row["archived_at"], "archive_reason": row["archive_reason"],
+            }
+            for row in rows
+        ]
+
+    def restore_archived(self, memory_id: str) -> MemoryRecord:
+        """Bring an archived memory back into active recall.
+
+        The original expiry is cleared — restoring an expired memory that
+        stays expired would be a no-op — and updated_at restarts the decay
+        clock, because a human decision to restore IS a relevance signal.
+        """
+        row = self.conn.execute(
+            "SELECT * FROM memories_archive WHERE id = ?", (memory_id,)
+        ).fetchone()
+        if row is None:
+            raise KeyError(memory_id)
+        now = utc_now()
+        self.conn.execute(
+            f"""
+            INSERT INTO memories({self._MEMORY_COLUMNS})
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                row["id"], row["owner"], row["scope"], row["type"], row["content"],
+                row["summary"], row["tags"], row["visibility"], row["source"],
+                row["confidence"], row["importance"], row["created_at"], now,
+                None, row["decay_policy"], row["decay_half_life_days"],
+                row["last_accessed_at"], row["access_count"], row["pinned"],
+            ),
+        )
+        self.conn.execute("DELETE FROM memories_archive WHERE id = ?", (memory_id,))
+        self.conn.commit()
+        return self.get(memory_id)
+
     def purge_owner(self, owner: str) -> dict[str, int]:
         """Delete every memory owned by `owner`, plus all links touching them.
 
@@ -1519,7 +1734,9 @@ class MemoryStore:
             "stale_links": int(stale_links),
             "top_hubs": top_hubs,
         }
+        archived = self.conn.execute("SELECT COUNT(*) FROM memories_archive").fetchone()[0]
         return base | {
+            "archived": int(archived),
             "graph_health": graph_health,
             "pinned": int(pinned),
             "expired": int(expired),

agent_memory_os-0.3.0/src/agent_memory_os/embedding.py

@@ -0,0 +1,114 @@
+"""Embedding pipeline: semantic recall that works out of the box.
+
+`HashingEmbedder` is the dependency-free default — deterministic feature
+hashing over words and character trigrams. It captures lexical similarity in
+vector space (typo- and morphology-tolerant), not deep semantics; swap in any
+real embedding model by passing a `str -> sequence[float]` callable.
+
+`AutoSemanticIndex` keeps a turbovec index in sync with the memories table by
+watching a cheap change signature and rebuilding lazily — the disposable-index
+philosophy: the vector index is never authoritative and can always be rebuilt
+from SQLite.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import zlib
+from typing import Iterable, Sequence
+
+from .candidates import Candidate
+
+_WORD_RE = re.compile(r"\w+", re.UNICODE)
+
+
+class HashingEmbedder:
+    """Deterministic feature-hashing embedder (no model, no downloads)."""
+
+    def __init__(self, dim: int = 256):
+        if dim < 16:
+            raise ValueError("dim must be >= 16")
+        self.dim = dim
+
+    def __call__(self, text: str) -> list[float]:
+        vector = [0.0] * self.dim
+        for feature in self._features(text):
+            digest = zlib.crc32(feature.encode("utf-8"))
+            index = digest % self.dim
+            sign = 1.0 if (digest >> 16) & 1 else -1.0
+            vector[index] += sign
+        norm = math.sqrt(sum(value * value for value in vector))
+        if norm == 0.0:
+            return vector
+        return [value / norm for value in vector]
+
+    @staticmethod
+    def _features(text: str) -> Iterable[str]:
+        words = _WORD_RE.findall(text.lower())
+        for word in words:
+            yield "w:" + word
+            padded = f"^{word}$"
+            for i in range(len(padded) - 2):
+                yield "t:" + padded[i : i + 3]
+
+
+class AutoSemanticIndex:
+    """CandidateProvider that self-maintains a turbovec index over the store.
+
+    Rebuilds whenever the memories table changes (count / max rowid / max
+    updated_at signature), so no write-path coupling is needed and multiple
+    processes sharing the database each converge on their own fresh index.
+    Returns candidate ids only; the store's ACL/expiry hard gates still apply.
+    """
+
+    name = "turbovec-auto"
+
+    def __init__(self, store, embedder=None, *, dim: int = 256):
+        self._store = store
+        self._embedder = embedder or HashingEmbedder(dim)
+        self._provider = None
+        self._signature: tuple | None = None
+
+    def candidates(
+        self,
+        query: str,
+        *,
+        owner: str | None = None,
+        scope: str | None = None,
+        requester_agent_id: str | None = None,
+        requester_team_id: str | None = None,
+        limit: int = 10,
+    ) -> Sequence[Candidate]:
+        signature = self._store.semantic_signature()
+        if signature != self._signature:
+            self._rebuild(signature)
+        if self._provider is None:
+            return []
+        return list(
+            self._provider.candidates(
+                query,
+                owner=owner,
+                scope=scope,
+                requester_agent_id=requester_agent_id,
+                requester_team_id=requester_team_id,
+                limit=limit,
+            )
+        )
+
+    def _rebuild(self, signature: tuple) -> None:
+        from .providers.turbovec import TurbovecSemanticCandidateProvider
+
+        corpus = self._store.semantic_corpus()
+        if not corpus:
+            self._provider = None
+            self._signature = signature
+            return
+        vectors = [self._embedder(text) for _, _, text in corpus]
+        mapping = {memory_id: rowid for rowid, memory_id, _ in corpus}
+        self._provider = TurbovecSemanticCandidateProvider.from_vectors(
+            vectors=vectors,
+            external_id_by_memory_id=mapping,
+            embed_query=self._embedder,
+        )
+        self._signature = signature