memoryagent-lib 0.1.1__py3-none-any.whl

memoryagent/storage/in_memory.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import datetime, timezone
+from typing import Dict, List
+
+from memoryagent.models import MemoryQuery, MemoryType, ScoredMemory, StorageTier
+from memoryagent.storage.base import GraphStore, VectorIndex
+from memoryagent.utils import tokenize
+
+
+class SimpleVectorIndex(VectorIndex):
+    """Local in-memory lexical index used for local mode."""
+
+    def __init__(self) -> None:
+        self._tokens: Dict[str, List[str]] = defaultdict(list)
+        self._metadata: Dict[str, dict] = {}
+        self._texts: Dict[str, str] = {}
+
+    async def upsert(self, item_id, text: str, metadata: dict) -> None:
+        item_id = str(item_id)
+        self._texts[item_id] = text
+        self._metadata[item_id] = metadata
+        for token in set(tokenize(text)):
+            if item_id not in self._tokens[token]:
+                self._tokens[token].append(item_id)
+
+    async def delete(self, item_id) -> None:
+        item_id = str(item_id)
+        self._texts.pop(item_id, None)
+        self._metadata.pop(item_id, None)
+        for token, ids in list(self._tokens.items()):
+            if item_id in ids:
+                ids.remove(item_id)
+            if not ids:
+                self._tokens.pop(token, None)
+
+    async def query(self, query: MemoryQuery, filters: dict, limit: int) -> List[ScoredMemory]:
+        query_tokens = set(tokenize(query.text))
+        if not query_tokens:
+            return []
+
+        candidate_scores: Dict[str, int] = {}
+        for token in query_tokens:
+            for item_id in self._tokens.get(token, []):
+                candidate_scores[item_id] = candidate_scores.get(item_id, 0) + 1
+
+        scored: List[ScoredMemory] = []
+        for item_id, overlap in candidate_scores.items():
+            meta = self._metadata.get(item_id, {})
+            if filters:
+                if "owner" in filters and meta.get("owner") != filters["owner"]:
+                    continue
+                if "tier" in filters and meta.get("tier") != filters["tier"]:
+                    continue
+                if "types" in filters:
+                    if meta.get("type") not in {t.value for t in filters["types"]}:
+                        continue
+            score = overlap / max(1, len(query_tokens))
+            meta_tier = meta.get("tier")
+            tier_value = StorageTier(meta_tier) if meta_tier else meta["item"].tier
+            scored.append(
+                ScoredMemory(
+                    item=meta["item"],
+                    score=score,
+                    tier=tier_value,
+                    explanation="token overlap",
+                )
+            )
+
+        scored.sort(key=lambda item: item.score, reverse=True)
+        return scored[:limit]
+
+
+class SimpleGraphStore(GraphStore):
+    def __init__(self) -> None:
+        self._edges: Dict[str, List[str]] = defaultdict(list)
+
+    async def upsert_fact(self, owner: str, subject: str, predicate: str, obj: str) -> None:
+        key = f"{owner}:{subject}:{predicate}"
+        self._edges[key].append(obj)
+
+    async def query_related(self, owner: str, subject: str, limit: int) -> List[str]:
+        results: List[str] = []
+        for key, targets in self._edges.items():
+            if key.startswith(f"{owner}:{subject}:"):
+                results.extend(targets)
+        return results[:limit]

memoryagent/storage/local_disk.py

@@ -0,0 +1,415 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+from memoryagent.models import MemoryItem, MemoryQuery, MemoryType, ScoredMemory, StorageTier, utc_now
+from memoryagent.storage.base import FeatureStore, MetadataStore, ObjectStore, VectorIndex
+from memoryagent.utils import clamp, hash_embed
+
+
+class SQLiteMetadataStore(MetadataStore):
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self._init_db()
+
+    def _init_db(self) -> None:
+        with sqlite3.connect(self.path) as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS memory_items (
+                    id TEXT PRIMARY KEY,
+                    type TEXT,
+                    owner TEXT,
+                    summary TEXT,
+                    content_json TEXT,
+                    tags_json TEXT,
+                    created_at TEXT,
+                    updated_at TEXT,
+                    last_accessed TEXT,
+                    tier TEXT,
+                    pointer_json TEXT,
+                    ttl_seconds INTEGER,
+                    confidence REAL,
+                    authority REAL,
+                    stability REAL
+                )
+                """
+            )
+
+    async def upsert(self, item: MemoryItem) -> None:
+        await asyncio.to_thread(self._upsert_sync, item)
+
+    def _upsert_sync(self, item: MemoryItem) -> None:
+        now = utc_now().isoformat()
+        item.updated_at = utc_now()
+        with sqlite3.connect(self.path) as conn:
+            conn.execute(
+                """
+                INSERT INTO memory_items (
+                    id, type, owner, summary, content_json, tags_json,
+                    created_at, updated_at, last_accessed, tier, pointer_json,
+                    ttl_seconds, confidence, authority, stability
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(id) DO UPDATE SET
+                    type=excluded.type,
+                    owner=excluded.owner,
+                    summary=excluded.summary,
+                    content_json=excluded.content_json,
+                    tags_json=excluded.tags_json,
+                    created_at=excluded.created_at,
+                    updated_at=excluded.updated_at,
+                    last_accessed=excluded.last_accessed,
+                    tier=excluded.tier,
+                    pointer_json=excluded.pointer_json,
+                    ttl_seconds=excluded.ttl_seconds,
+                    confidence=excluded.confidence,
+                    authority=excluded.authority,
+                    stability=excluded.stability
+                """,
+                (
+                    str(item.id),
+                    item.type.value,
+                    item.owner,
+                    item.summary,
+                    json.dumps(item.content, ensure_ascii=True),
+                    json.dumps(item.tags, ensure_ascii=True),
+                    item.created_at.isoformat(),
+                    item.updated_at.isoformat(),
+                    item.last_accessed.isoformat() if item.last_accessed else None,
+                    item.tier.value,
+                    json.dumps(item.pointer, ensure_ascii=True),
+                    item.ttl_seconds,
+                    item.confidence,
+                    item.authority,
+                    item.stability,
+                ),
+            )
+
+    async def get(self, item_id) -> Optional[MemoryItem]:
+        return await asyncio.to_thread(self._get_sync, item_id)
+
+    def _get_sync(self, item_id) -> Optional[MemoryItem]:
+        with sqlite3.connect(self.path) as conn:
+            row = conn.execute(
+                "SELECT id, type, owner, summary, content_json, tags_json, created_at, updated_at, last_accessed, tier, pointer_json, ttl_seconds, confidence, authority, stability FROM memory_items WHERE id = ?",
+                (str(item_id),),
+            ).fetchone()
+        if not row:
+            return None
+        return _row_to_item(row)
+
+    async def delete(self, item_id) -> None:
+        await asyncio.to_thread(self._delete_sync, item_id)
+
+    def _delete_sync(self, item_id) -> None:
+        with sqlite3.connect(self.path) as conn:
+            conn.execute("DELETE FROM memory_items WHERE id = ?", (str(item_id),))
+
+    async def list_by_owner(self, owner: str) -> List[MemoryItem]:
+        return await asyncio.to_thread(self._list_by_owner_sync, owner)
+
+    def _list_by_owner_sync(self, owner: str) -> List[MemoryItem]:
+        with sqlite3.connect(self.path) as conn:
+            rows = conn.execute(
+                "SELECT id, type, owner, summary, content_json, tags_json, created_at, updated_at, last_accessed, tier, pointer_json, ttl_seconds, confidence, authority, stability FROM memory_items WHERE owner = ?",
+                (owner,),
+            ).fetchall()
+        return [_row_to_item(row) for row in rows]
+
+    async def list_by_owner_and_type(self, owner: str, types: Iterable[str]) -> List[MemoryItem]:
+        return await asyncio.to_thread(self._list_by_owner_and_type_sync, owner, list(types))
+
+    def _list_by_owner_and_type_sync(self, owner: str, types: List[str]) -> List[MemoryItem]:
+        placeholders = ",".join("?" for _ in types)
+        with sqlite3.connect(self.path) as conn:
+            rows = conn.execute(
+                f"SELECT id, type, owner, summary, content_json, tags_json, created_at, updated_at, last_accessed, tier, pointer_json, ttl_seconds, confidence, authority, stability FROM memory_items WHERE owner = ? AND type IN ({placeholders})",
+                (owner, *types),
+            ).fetchall()
+        return [_row_to_item(row) for row in rows]
+
+    async def update_access(self, item_id) -> None:
+        await asyncio.to_thread(self._update_access_sync, item_id)
+
+    def _update_access_sync(self, item_id) -> None:
+        with sqlite3.connect(self.path) as conn:
+            conn.execute(
+                "UPDATE memory_items SET last_accessed = ? WHERE id = ?",
+                (utc_now().isoformat(), str(item_id)),
+            )
+
+
+class FileObjectStore(ObjectStore):
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    async def put(self, key: str, payload: dict) -> str:
+        return await asyncio.to_thread(self._put_sync, key, payload)
+
+    def _put_sync(self, key: str, payload: dict) -> str:
+        path = self._resolve_path(key)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = path.with_suffix(".json.tmp")
+        tmp_path.write_text(json.dumps(payload, ensure_ascii=True, indent=2), encoding="utf-8")
+        tmp_path.replace(path)
+        return str(path)
+
+    async def get(self, key: str) -> Optional[dict]:
+        return await asyncio.to_thread(self._get_sync, key)
+
+    def _get_sync(self, key: str) -> Optional[dict]:
+        path = self._resolve_path(key)
+        if not path.exists():
+            return None
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def _resolve_path(self, key: str) -> Path:
+        if key.endswith(".json"):
+            relative = Path(key)
+        else:
+            relative = Path(f"{key}.json")
+        if relative.is_absolute():
+            return relative
+        return self.root / relative
+
+    async def append(self, key: str, payload: dict) -> str:
+        return await asyncio.to_thread(self._append_sync, key, payload)
+
+    def _append_sync(self, key: str, payload: dict) -> str:
+        path = self._resolve_path(key)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        existing = []
+        if path.exists():
+            try:
+                existing = json.loads(path.read_text(encoding="utf-8"))
+            except Exception:
+                existing = []
+        if not isinstance(existing, list):
+            existing = []
+        existing.append(payload)
+        tmp_path = path.with_suffix(".json.tmp")
+        tmp_path.write_text(json.dumps(existing, ensure_ascii=True, indent=2), encoding="utf-8")
+        tmp_path.replace(path)
+        return str(path)
+
+
+class SQLiteFeatureStore(FeatureStore):
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self._init_db()
+
+    def _init_db(self) -> None:
+        with sqlite3.connect(self.path) as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS features (
+                    owner TEXT,
+                    created_at TEXT,
+                    payload_json TEXT
+                )
+                """
+            )
+
+    async def write_feature(self, owner: str, payload: dict) -> None:
+        await asyncio.to_thread(self._write_feature_sync, owner, payload)
+
+    def _write_feature_sync(self, owner: str, payload: dict) -> None:
+        with sqlite3.connect(self.path) as conn:
+            conn.execute(
+                "INSERT INTO features (owner, created_at, payload_json) VALUES (?, ?, ?)",
+                (owner, utc_now().isoformat(), json.dumps(payload, ensure_ascii=True)),
+            )
+
+    async def query_features(self, owner: str, limit: int) -> List[dict]:
+        return await asyncio.to_thread(self._query_features_sync, owner, limit)
+
+    def _query_features_sync(self, owner: str, limit: int) -> List[dict]:
+        with sqlite3.connect(self.path) as conn:
+            rows = conn.execute(
+                "SELECT payload_json FROM features WHERE owner = ? ORDER BY created_at DESC LIMIT ?",
+                (owner, limit),
+            ).fetchall()
+        return [json.loads(row[0]) for row in rows]
+
+
+class SQLiteVecIndex(VectorIndex):
+    """Vector search via sqlite-vec (optional extension)."""
+
+    def __init__(
+        self,
+        path: Path,
+        dim: int,
+        embedding_fn=None,
+        extension_path: Optional[Path] = None,
+    ) -> None:
+        self.path = path
+        self.dim = dim
+        self.embedding_fn = embedding_fn or (lambda text: hash_embed(text, dim))
+        self.extension_path = extension_path
+        self._init_db()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.path)
+        conn.row_factory = sqlite3.Row
+        conn.enable_load_extension(True)
+        if not self._try_load_extension(conn):
+            raise RuntimeError(
+                "sqlite-vec extension not available. Install sqlite-vec or provide extension_path."
+            )
+        return conn
+
+    def _try_load_extension(self, conn: sqlite3.Connection) -> bool:
+        try:
+            import sqlite_vec  # type: ignore
+
+            sqlite_vec.load(conn)
+            return True
+        except Exception:
+            if self.extension_path is None:
+                return False
+            conn.load_extension(str(self.extension_path))
+            return True
+
+    def _init_db(self) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                f"""
+                CREATE VIRTUAL TABLE IF NOT EXISTS vec_items USING vec0(
+                    item_id TEXT PRIMARY KEY,
+                    owner TEXT,
+                    tier TEXT,
+                    type TEXT,
+                    embedding FLOAT[{self.dim}],
+                    +item_json TEXT
+                )
+                """
+            )
+
+    async def upsert(self, item_id, text: str, metadata: dict) -> None:
+        await asyncio.to_thread(self._upsert_sync, item_id, text, metadata)
+
+    def _serialize_embedding(self, embedding: List[float]):
+        try:
+            import sqlite_vec  # type: ignore
+
+            return sqlite_vec.serialize_float32(embedding)
+        except Exception:
+            return json.dumps(embedding, ensure_ascii=True)
+
+    def _upsert_sync(self, item_id, text: str, metadata: dict) -> None:
+        item = metadata.get("item")
+        if item is None:
+            raise ValueError("SQLiteVecIndex expects metadata['item'] to be a MemoryItem")
+        embedding = self.embedding_fn(text)
+        item_json = item.model_dump_json(
+            include={"id", "type", "owner", "summary", "tier", "pointer"}
+        )
+        with self._connect() as conn:
+            conn.execute("DELETE FROM vec_items WHERE item_id = ?", (str(item_id),))
+            conn.execute(
+                """
+                INSERT INTO vec_items (item_id, owner, tier, type, embedding, item_json)
+                VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    str(item_id),
+                    metadata.get("owner"),
+                    metadata.get("tier"),
+                    metadata.get("type"),
+                    self._serialize_embedding(embedding),
+                    item_json,
+                ),
+            )
+
+    async def delete(self, item_id) -> None:
+        await asyncio.to_thread(self._delete_sync, item_id)
+
+    def _delete_sync(self, item_id) -> None:
+        with self._connect() as conn:
+            conn.execute("DELETE FROM vec_items WHERE item_id = ?", (str(item_id),))
+
+    async def query(self, query: MemoryQuery, filters: dict, limit: int) -> List[ScoredMemory]:
+        return await asyncio.to_thread(self._query_sync, query, filters, limit)
+
+    def _query_sync(self, query: MemoryQuery, filters: dict, limit: int) -> List[ScoredMemory]:
+        embedding = self.embedding_fn(query.text)
+        embedding_blob = self._serialize_embedding(embedding)
+
+        clauses = ["embedding MATCH ?"]
+        params: List[object] = [embedding_blob]
+
+        if filters.get("owner"):
+            clauses.append("owner = ?")
+            params.append(filters["owner"])
+        if filters.get("tier"):
+            clauses.append("tier = ?")
+            params.append(filters["tier"])
+        if filters.get("types"):
+            types = filters["types"]
+            placeholders = ",".join("?" for _ in types)
+            clauses.append(f"type IN ({placeholders})")
+            params.extend([t.value for t in types])
+
+        where_sql = " AND ".join(clauses)
+        sql = f"SELECT item_json, distance FROM vec_items WHERE {where_sql} ORDER BY distance LIMIT ?"
+        params.append(limit)
+
+        with self._connect() as conn:
+            rows = conn.execute(sql, params).fetchall()
+
+        scored: List[ScoredMemory] = []
+        for row in rows:
+            item = MemoryItem.model_validate_json(row["item_json"])
+            distance = row["distance"]
+            score = clamp(1.0 / (1.0 + distance))
+            scored.append(ScoredMemory(item=item, score=score, tier=item.tier, explanation="sqlite-vec"))
+        return scored
+
+
+def _row_to_item(row) -> MemoryItem:
+    (
+        item_id,
+        item_type,
+        owner,
+        summary,
+        content_json,
+        tags_json,
+        created_at,
+        updated_at,
+        last_accessed,
+        tier,
+        pointer_json,
+        ttl_seconds,
+        confidence,
+        authority,
+        stability,
+    ) = row
+    return MemoryItem(
+        id=item_id,
+        type=MemoryType(item_type),
+        owner=owner,
+        summary=summary,
+        content=json.loads(content_json) if content_json else None,
+        tags=json.loads(tags_json) if tags_json else [],
+        created_at=datetime_from_iso(created_at),
+        updated_at=datetime_from_iso(updated_at),
+        last_accessed=datetime_from_iso(last_accessed) if last_accessed else None,
+        tier=StorageTier(tier),
+        pointer=json.loads(pointer_json) if pointer_json else {},
+        ttl_seconds=ttl_seconds,
+        confidence=confidence,
+        authority=authority,
+        stability=stability,
+    )
+
+
+def datetime_from_iso(value: Optional[str]):
+    if not value:
+        return utc_now()
+    return datetime.fromisoformat(value)

memoryagent/system.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Dict, Optional, Union
+
+from memoryagent.config import MemorySystemConfig
+from memoryagent.indexers import EpisodicIndexer, PerceptualIndexer, SemanticGraphIndexer
+from memoryagent.models import MemoryEvent, MemoryItem, MemoryQuery, MemoryType, StorageTier
+from memoryagent.policy import MemoryRoutingPolicy
+from memoryagent.retrieval import RetrievalOrchestrator
+from memoryagent.storage.base import FeatureStore, GraphStore, MetadataStore, ObjectStore, VectorIndex
+from memoryagent.utils import tokenize
+from memoryagent.storage.in_memory import SimpleGraphStore, SimpleVectorIndex
+from memoryagent.storage.local_disk import (
+    FileObjectStore,
+    SQLiteFeatureStore,
+    SQLiteMetadataStore,
+    SQLiteVecIndex,
+)
+from memoryagent.workers import ArchiverWorker, Compactor, ConsolidationWorker, RehydratorWorker
+
+
+class MemorySystem:
+    """Entry point for the memory framework with local-mode defaults."""
+
+    def __init__(
+        self,
+        config: Optional[MemorySystemConfig] = None,
+        metadata_store: Optional[MetadataStore] = None,
+        vector_index: Optional[VectorIndex] = None,
+        graph_store: Optional[GraphStore] = None,
+        object_store: Optional[ObjectStore] = None,
+        feature_store: Optional[FeatureStore] = None,
+        embedding_fn=None,
+        routing_policy: Optional[MemoryRoutingPolicy] = None,
+    ) -> None:
+        self.config = config or MemorySystemConfig()
+        self.metadata_store = metadata_store or SQLiteMetadataStore(self.config.metadata_db_path)
+        if vector_index is not None:
+            self.vector_index = vector_index
+        elif self.config.use_sqlite_vec:
+            self.vector_index = SQLiteVecIndex(
+                path=self.config.vector_db_path,
+                dim=self.config.vector_dim,
+                embedding_fn=embedding_fn,
+                extension_path=self.config.sqlite_vec_extension_path,
+            )
+        else:
+            self.vector_index = SimpleVectorIndex()
+        self.graph_store = graph_store or SimpleGraphStore()
+        self.object_store = object_store or FileObjectStore(self.config.cold_store_path / "records")
+        self.feature_store = feature_store or SQLiteFeatureStore(self.config.feature_db_path)
+
+        self.episodic_indexer = EpisodicIndexer(self.vector_index)
+        self.semantic_indexer = SemanticGraphIndexer(self.graph_store)
+        self.perceptual_indexer = PerceptualIndexer(self.feature_store)
+        self.routing_policy = routing_policy or MemoryRoutingPolicy()
+
+        self.retrieval = RetrievalOrchestrator(
+            metadata_store=self.metadata_store,
+            vector_index=self.vector_index,
+            object_store=self.object_store,
+            plan=self.config.retrieval_plan,
+        )
+
+        self.consolidation_worker = ConsolidationWorker(
+            metadata_store=self.metadata_store,
+            vector_index=self.vector_index,
+            config=self.config,
+        )
+        self.archiver_worker = ArchiverWorker(
+            metadata_store=self.metadata_store,
+            object_store=self.object_store,
+            vector_index=self.vector_index,
+        )
+        self.rehydrator_worker = RehydratorWorker(
+            metadata_store=self.metadata_store,
+            vector_index=self.vector_index,
+        )
+        self.compactor = Compactor(self.metadata_store)
+
+        self.metrics: Dict[str, int] = {
+            "requests": 0,
+            "hot_hit": 0,
+            "archive_escalation": 0,
+            "cold_fetch": 0,
+            "thrash_detected": 0,
+            "tokens_returned": 0,
+            "tokens_saved_estimate": 0,
+        }
+
+    def write(self, event: Union[MemoryEvent, MemoryItem, dict]) -> None:
+        self._run_async(self.write_async(event))
+
+    async def write_async(self, event: Union[MemoryEvent, MemoryItem, dict]) -> MemoryItem:
+        item = self._coerce_event(event)
+        if item.type == MemoryType.WORKING and item.ttl_seconds is None:
+            item.ttl_seconds = self.config.working_ttl_seconds
+        decision = self.routing_policy.route(item)
+        if decision.write_hot:
+            await self.metadata_store.upsert(item)
+        if decision.write_vector:
+            await self.episodic_indexer.index_hot(item)
+        if decision.write_features:
+            await self.perceptual_indexer.index(item)
+        await self.semantic_indexer.index(item)
+        return item
+
+    def write_perceptual(self, payload: Union[MemoryEvent, MemoryItem, dict]) -> None:
+        self._run_async(self.write_perceptual_async(payload))
+
+    async def write_perceptual_async(self, payload: Union[MemoryEvent, MemoryItem, dict]) -> MemoryItem:
+        item = self._coerce_event(payload)
+        item.type = MemoryType.PERCEPTUAL
+        decision = self.routing_policy.route(item)
+        if decision.write_hot:
+            await self.metadata_store.upsert(item)
+        if decision.write_vector:
+            await self.episodic_indexer.index_hot(item)
+        if decision.write_features:
+            await self.perceptual_indexer.index(item)
+        return item
+
+    def retrieve(self, query: Union[MemoryQuery, str], owner: Optional[str] = None):
+        return self._run_async(self.retrieve_async(query, owner))
+
+    async def retrieve_async(self, query: Union[MemoryQuery, str], owner: Optional[str] = None):
+        if isinstance(query, str):
+            if not owner:
+                raise ValueError("owner is required when query is a string")
+            query = MemoryQuery(text=query, owner=owner)
+        bundle = await self.retrieval.retrieve(query)
+        self.metrics["requests"] += 1
+        if StorageTier.ARCHIVE_INDEX in bundle.used_tiers:
+            self.metrics["archive_escalation"] += 1
+        if StorageTier.COLD in bundle.used_tiers:
+            self.metrics["cold_fetch"] += 1
+        if bundle.used_tiers and bundle.used_tiers[0] == StorageTier.HOT:
+            self.metrics["hot_hit"] += 1
+        returned_tokens = sum(len(tokenize(block.text)) for block in bundle.blocks)
+        self.metrics["tokens_returned"] += returned_tokens
+        baseline = self.config.retrieval_plan.max_results * 50
+        self.metrics["tokens_saved_estimate"] += max(0, baseline - returned_tokens)
+        return bundle
+
+    def flush(self, owner: str):
+        return self._run_async(self.flush_async(owner))
+
+    async def flush_async(self, owner: str):
+        new_items = await self.consolidation_worker.run_once(owner)
+        if self.config.consolidation.archive_on_flush:
+            await self.archiver_worker.run_once(owner)
+        await self.compactor.run_once(owner)
+        return new_items
+
+    async def record_access(self, item_id) -> None:
+        await self.rehydrator_worker.record_access(item_id)
+        await self.metadata_store.update_access(item_id)
+
+    async def rehydrate(self, owner: str):
+        warmed = await self.rehydrator_worker.run_once(owner)
+        if warmed:
+            self.metrics["thrash_detected"] += 1
+        return warmed
+
+    def _coerce_event(self, event: Union[MemoryEvent, MemoryItem, dict]) -> MemoryItem:
+        if isinstance(event, MemoryItem):
+            return event
+        if isinstance(event, MemoryEvent):
+            return event.to_item()
+        if isinstance(event, dict):
+            return MemoryEvent(**event).to_item()
+        raise TypeError("Unsupported event payload")
+
+    def _run_async(self, coro):
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+        if loop and loop.is_running():
+            raise RuntimeError("MemorySystem sync API called inside an event loop; use *_async methods.")
+        return asyncio.run(coro)