agent-memory-os 0.2.3__py3-none-any.whl

agent_memory_os/__init__.py

@@ -0,0 +1,17 @@
+"""AgentMemoryOS public SDK."""
+
+from .client import MemoryClient
+from .golden_recall import evaluate_golden_queries, load_golden_query_cases
+from .hermes_importer import import_hermes_memory_files
+from .schema import MemoryLink, MemoryRecord, RecallProfile, SearchResult
+
+__all__ = [
+    "MemoryClient",
+    "MemoryLink",
+    "MemoryRecord",
+    "RecallProfile",
+    "SearchResult",
+    "evaluate_golden_queries",
+    "import_hermes_memory_files",
+    "load_golden_query_cases",
+]

agent_memory_os/cache.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Generic, TypeVar
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class LRUCache(Generic[K, V]):
+    def __init__(self, max_items: int = 512):
+        if max_items < 1:
+            raise ValueError("max_items must be >= 1")
+        self.max_items = max_items
+        self._items: OrderedDict[K, V] = OrderedDict()
+
+    def get(self, key: K) -> V | None:
+        if key not in self._items:
+            return None
+        self._items.move_to_end(key)
+        return self._items[key]
+
+    def set(self, key: K, value: V) -> None:
+        self._items[key] = value
+        self._items.move_to_end(key)
+        while len(self._items) > self.max_items:
+            self._items.popitem(last=False)
+
+    def clear(self) -> None:
+        self._items.clear()
+
+    def __len__(self) -> int:
+        return len(self._items)

agent_memory_os/candidates.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Protocol
+
+
+@dataclass(slots=True)
+class Candidate:
+    """Untrusted retrieval candidate produced by a disposable index/provider.
+
+    Candidate providers may suggest stable MemoryRecord IDs and scoring metadata.
+    They must not be treated as authoritative content sources; callers must rejoin
+    every candidate through SQLite and apply ACL/expiry hard gates before use.
+    """
+
+    memory_id: str
+    provider: str
+    score: float
+    rank: int | None = None
+    reason: str = ""
+
+
+class CandidateProvider(Protocol):
+    """Protocol for untrusted retrieval candidate sidecars."""
+
+    name: str
+
+    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,
+    ) -> Iterable[Candidate]:
+        """Return untrusted candidate IDs and scores for later SQLite rejoin."""
+        ...

agent_memory_os/cli.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import argparse
+import json
+from .client import MemoryClient
+from .golden_recall import evaluate_golden_queries, load_golden_query_cases
+from .hermes_importer import import_hermes_memory_files
+from .shadow_mode import summarize_shadow_log
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="agent-memory", description="Local-first AI agent memory runtime")
+    p.add_argument("--home", default=None, help="Memory home directory; defaults to AGENT_MEMORY_HOME or ~/.agent-memory")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    add = sub.add_parser("add", help="Add a memory")
+    add.add_argument("content")
+    add.add_argument("--owner", default="default")
+    add.add_argument("--scope", default="user")
+    add.add_argument("--type", default="note")
+    add.add_argument("--summary")
+    add.add_argument("--tag", action="append", default=[])
+    add.add_argument("--confidence", type=float, default=0.8)
+    add.add_argument("--importance", type=float, default=0.5)
+
+    search = sub.add_parser("search", help="Search memories")
+    search.add_argument("query")
+    search.add_argument("--owner")
+    search.add_argument("--scope")
+    search.add_argument("--limit", type=int, default=10)
+    search.add_argument("--json", action="store_true")
+
+    pack = sub.add_parser("pack", help="Build a prompt-ready context pack")
+    pack.add_argument("query")
+    pack.add_argument("--owner")
+    pack.add_argument("--scope")
+    pack.add_argument("--limit", type=int, default=12)
+    pack.add_argument("--max-tokens", type=int, default=1200)
+
+    sub.add_parser("stats", help="Show database statistics")
+
+    imp = sub.add_parser("import-hermes", help="Import Hermes MEMORY.md/USER.md into AgentMemoryOS")
+    imp.add_argument("--profile", required=True, help="Hermes profile name / AgentMemoryOS owner")
+    imp.add_argument("--profile-home", required=True, help="Hermes profile home containing memories/MEMORY.md and USER.md")
+    imp.add_argument("--json", action="store_true", help="Emit JSON report")
+
+    shadow = sub.add_parser("shadow-summary", help="Summarize shadow-mode JSONL evidence")
+    shadow.add_argument("--log", required=True, help="Path to agent_memory_os_shadow.jsonl")
+    shadow.add_argument("--last", type=int, default=None, help="Only summarize the last N records")
+    shadow.add_argument("--json", action="store_true", help="Emit JSON evidence pack")
+
+    golden = sub.add_parser("golden-recall", help="Run golden-query recall cases against the memory store")
+    golden.add_argument("--cases", required=True, help="JSON/JSONL golden query case file")
+    golden.add_argument("--limit", type=int, default=10, help="Default search limit for cases without limit")
+    golden.add_argument("--recall-target", type=float, default=0.95, help="Required pass rate for GO")
+    golden.add_argument("--json", action="store_true", help="Emit JSON evidence report")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "shadow-summary":
+        summary = summarize_shadow_log(args.log, last_n=args.last)
+        if args.json:
+            print(json.dumps(summary, ensure_ascii=False, indent=2, sort_keys=True))
+        else:
+            print(
+                f"records={summary['records']} activation_gate={summary['activation_gate']} "
+                f"mean_top_k_hit_rate={summary['mean_top_k_hit_rate']} "
+                f"p99_candidate_latency_ms={summary['p99_candidate_latency_ms']} "
+                f"acl_leakage_count={summary['acl_leakage_count']} "
+                f"production_injection_count={summary['production_injection_count']}"
+            )
+        return 0
+
+    client = MemoryClient(home=args.home)
+    try:
+        if args.command == "golden-recall":
+            cases = load_golden_query_cases(args.cases)
+            report = evaluate_golden_queries(
+                client,
+                cases,
+                default_limit=args.limit,
+                recall_target=args.recall_target,
+            )
+            if args.json:
+                print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True))
+            else:
+                print(
+                    f"cases={report['cases']} passed={report['passed']} failed={report['failed']} "
+                    f"golden_recall_rate={report['golden_recall_rate']} "
+                    f"forbidden_hit_count={report['forbidden_hit_count']} "
+                    f"activation_gate={report['activation_gate']}"
+                )
+            return 0
+        if args.command == "add":
+            rec = client.add(
+                args.content, owner=args.owner, scope=args.scope, type=args.type,
+                summary=args.summary, tags=args.tag, confidence=args.confidence, importance=args.importance,
+            )
+            print(rec.id)
+            return 0
+        if args.command == "search":
+            results = client.search(args.query, owner=args.owner, scope=args.scope, limit=args.limit)
+            if args.json:
+                print(json.dumps([
+                    {"id": r.record.id, "score": r.score, "content": r.record.content, "scope": r.record.scope, "type": r.record.type}
+                    for r in results
+                ], ensure_ascii=False, indent=2))
+            else:
+                for r in results:
+                    print(f"{r.record.id}\t{r.score:.3f}\t{r.record.scope}/{r.record.type}\t{r.record.content}")
+            return 0
+        if args.command == "pack":
+            print(client.context_pack(args.query, owner=args.owner, scope=args.scope, limit=args.limit, max_tokens=args.max_tokens), end="")
+            return 0
+        if args.command == "stats":
+            print(json.dumps(client.stats(), ensure_ascii=False, indent=2))
+            return 0
+        if args.command == "import-hermes":
+            report = import_hermes_memory_files(client, profile=args.profile, profile_home=args.profile_home)
+            if args.json:
+                print(json.dumps(report.as_dict(), ensure_ascii=False, indent=2))
+            else:
+                print(
+                    f"profile={report.profile} scanned={report.scanned} inserted={report.inserted} "
+                    f"updated={report.updated} skipped={report.skipped}"
+                )
+            return 0
+    finally:
+        client.close()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_memory_os/client.py

@@ -0,0 +1,434 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+import os
+from datetime import datetime, timezone
+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 .schema import MemoryLink, MemoryRecord, RecallProfile, SearchResult
+
+class MemoryClient:
+    def __init__(
+        self,
+        home: str | Path | None = None,
+        *,
+        cache_items: int = 512,
+        candidate_providers: Sequence[CandidateProvider] | None = None,
+        resonance_hops: int = 1,
+        profile: RecallProfile | None = None,
+        check_same_thread: bool = True,
+    ):
+        home_path = Path(home or os.getenv("AGENT_MEMORY_HOME", "~/.agent-memory")).expanduser()
+        self.home = home_path
+        self.store = MemoryStore(
+            home_path / "memories.db",
+            candidate_providers=candidate_providers,
+            resonance_hops=resonance_hops,
+            check_same_thread=check_same_thread,
+        )
+        self.profile = profile
+        self.cache: LRUCache[tuple, object] = LRUCache(max_items=cache_items)
+        self._profile_cache: dict[str, RecallProfile | None] = {}
+
+    def add(self, content: str, *, auto_link: bool = False, **kwargs) -> MemoryRecord:
+        record = MemoryRecord(content=content, **kwargs)
+        saved = self.store.add(record)
+        if auto_link:
+            self.store.auto_link_similar(saved)
+        self.cache.clear()
+        return saved
+
+    def get(self, memory_id: str) -> MemoryRecord | None:
+        return self.store.get(memory_id)
+
+    def delete(self, memory_id: str) -> bool:
+        removed = self.store.delete(memory_id)
+        if removed:
+            self.cache.clear()
+        return removed
+
+    def update(self, memory_id: str, **fields) -> MemoryRecord:
+        updated = self.store.update_memory(memory_id, **fields)
+        self.cache.clear()
+        return updated
+
+    def dashboard_stats(self) -> dict[str, object]:
+        return self.store.dashboard_stats() | {"cache_items": len(self.cache)}
+
+    def list_recent(
+        self,
+        *,
+        owner: str | None = None,
+        scope: str | None = None,
+        memory_type: str | None = None,
+        requester_agent_id: str | None = None,
+        requester_team_id: str | None = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> list[MemoryRecord]:
+        return self.store.list_recent(
+            owner=owner,
+            scope=scope,
+            memory_type=memory_type,
+            requester_agent_id=requester_agent_id,
+            requester_team_id=requester_team_id,
+            limit=limit,
+            offset=offset,
+        )
+
+    def graph_snapshot(
+        self,
+        *,
+        requester_agent_id: str | None = None,
+        requester_team_id: str | None = None,
+        limit: int = 300,
+    ) -> dict[str, list[dict]]:
+        return self.store.graph_snapshot(
+            requester_agent_id=requester_agent_id,
+            requester_team_id=requester_team_id,
+            limit=limit,
+        )
+
+    def link(
+        self,
+        src_id: str,
+        dst_id: str,
+        *,
+        relation: str = "related_to",
+        weight: float = 0.5,
+        source: dict | None = None,
+    ) -> MemoryLink:
+        saved = self.store.add_link(
+            MemoryLink(src_id=src_id, dst_id=dst_id, relation=relation, weight=weight, source=source or {})
+        )
+        self.cache.clear()
+        return saved
+
+    def unlink(self, src_id: str, dst_id: str, *, relation: str | None = None) -> bool:
+        removed = self.store.remove_link(src_id, dst_id, relation=relation)
+        if removed:
+            self.cache.clear()
+        return removed
+
+    def links(self, memory_id: str) -> list[MemoryLink]:
+        return self.store.links_for(memory_id)
+
+    def record_recall(
+        self,
+        memory_ids: Sequence[str],
+        *,
+        create_colinks: bool = False,
+        helpful: bool = True,
+        requester_agent_id: str | None = None,
+        requester_team_id: str | None = None,
+    ) -> dict[str, int]:
+        """Report that these memories were recalled together.
+
+        This is the repeated-recall feedback loop: with `helpful=True` it
+        reinforces each memory and strengthens the association edges between
+        them so future queries resonate along well-worn paths; with
+        `helpful=False` the recall misled the agent, so links weaken and
+        confidence drops — the self-correction path. Pass the requester when
+        the feedback comes from an untrusted surface: only memories visible to
+        that requester are affected.
+        """
+        result = self.store.record_recall(
+            memory_ids,
+            create_colinks=create_colinks,
+            helpful=helpful,
+            requester_agent_id=requester_agent_id,
+            requester_team_id=requester_team_id,
+        )
+        self.cache.clear()
+        return result
+
+    def import_links(
+        self,
+        pairs: Sequence[tuple[str, str, float]],
+        *,
+        relation: str = "related_to",
+        source: dict | None = None,
+    ) -> int:
+        """Bulk-import derived association edges (e.g. from the ERA index).
+
+        Pairs whose endpoints no longer exist are skipped. Pairs already
+        connected (in either direction) are left untouched so a periodic sync
+        can never clobber reinforcement-learned weights.
+        """
+        imported = 0
+        for src_id, dst_id, weight in pairs:
+            if self.store.link_exists(src_id, dst_id):
+                continue
+            try:
+                self.store.add_link(
+                    MemoryLink(
+                        src_id=src_id, dst_id=dst_id, relation=relation,
+                        weight=weight, source=source or {"auto": "derived"},
+                    )
+                )
+                imported += 1
+            except (KeyError, ValueError):
+                continue
+        if imported:
+            self.cache.clear()
+        return imported
+
+    def save_profile(self, profile: RecallProfile) -> RecallProfile:
+        """Persist a named agent recall profile in the memory database."""
+        saved = self.store.save_profile(profile)
+        self._profile_cache.pop(profile.agent_id, None)
+        self.cache.clear()
+        return saved
+
+    def load_profile(self, agent_id: str) -> RecallProfile | None:
+        # Only cache hits: caching a miss forever would blind a long-running
+        # server to profiles saved later by another process.
+        cached = self._profile_cache.get(agent_id)
+        if cached is not None:
+            return cached
+        profile = self.store.load_profile(agent_id)
+        if profile is not None:
+            self._profile_cache[agent_id] = profile
+        return profile
+
+    def consolidate(self, *, owner: str | None = None, scope: str | None = None) -> dict[str, int]:
+        """Run the write-side hygiene pass: merge duplicates, synthesize concepts."""
+        result = self.store.consolidate(owner=owner, scope=scope)
+        self.cache.clear()
+        return result
+
+    def _resolve_profile(
+        self, profile: RecallProfile | None, requester_agent_id: str | None
+    ) -> RecallProfile | None:
+        if profile is not None:
+            return profile
+        if self.profile is not None:
+            return self.profile
+        if requester_agent_id:
+            return self.load_profile(requester_agent_id)
+        return None
+
+    def search(
+        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,
+        profile: RecallProfile | None = None,
+    ) -> list[SearchResult]:
+        active_profile = self._resolve_profile(profile, requester_agent_id)
+        profile_key = active_profile.signature() if active_profile else None
+        key = ("search", query, owner, scope, requester_agent_id, requester_team_id, limit, profile_key)
+        cached = self.cache.get(key)
+        if cached is not None:
+            return cached  # type: ignore[return-value]
+        results = self.store.search(
+            query,
+            owner=owner,
+            scope=scope,
+            requester_agent_id=requester_agent_id,
+            requester_team_id=requester_team_id,
+            limit=limit,
+            profile=active_profile,
+        )
+        self.cache.set(key, results)
+        return results
+
+    def context_pack(
+        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 = 12,
+        max_tokens: int = 1200,
+        profile: RecallProfile | None = None,
+        auto_reinforce: bool = False,
+    ) -> str:
+        if auto_reinforce:
+            return self.context_pack_report(
+                query,
+                owner=owner,
+                scope=scope,
+                requester_agent_id=requester_agent_id,
+                requester_team_id=requester_team_id,
+                limit=limit,
+                max_tokens=max_tokens,
+                profile=profile,
+                auto_reinforce=True,
+            ).text
+        active_profile = self._resolve_profile(profile, requester_agent_id)
+        profile_key = active_profile.signature() if active_profile else None
+        key = ("pack", query, owner, scope, requester_agent_id, requester_team_id, limit, max_tokens, profile_key)
+        cached = self.cache.get(key)
+        if cached is not None:
+            return cached  # type: ignore[return-value]
+        results = self.search(
+            query,
+            owner=owner,
+            scope=scope,
+            requester_agent_id=requester_agent_id,
+            requester_team_id=requester_team_id,
+            limit=limit,
+            profile=active_profile,
+        )
+        pack = build_context_pack(results, max_tokens=max_tokens)
+        self.cache.set(key, pack)
+        return pack
+
+    def context_pack_report(
+        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 = 12,
+        max_tokens: int = 1200,
+        profile: RecallProfile | None = None,
+        auto_reinforce: bool = False,
+    ) -> ContextPackReport:
+        active_profile = self._resolve_profile(profile, requester_agent_id)
+        profile_key = active_profile.signature() if active_profile else None
+        key = (
+            "pack_report", query, owner, scope, requester_agent_id, requester_team_id,
+            limit, max_tokens, profile_key,
+        )
+        if not auto_reinforce:
+            cached = self.cache.get(key)
+            if cached is not None:
+                return cached  # type: ignore[return-value]
+        results = self.search(
+            query,
+            owner=owner,
+            scope=scope,
+            requester_agent_id=requester_agent_id,
+            requester_team_id=requester_team_id,
+            limit=limit,
+            profile=active_profile,
+        )
+        report = build_context_pack_report(results, max_tokens=max_tokens)
+        if auto_reinforce:
+            # Selection is the recall event: close the reinforcement loop here
+            # so callers (especially MCP clients) don't have to remember to.
+            selected = [decision.memory_id for decision in report.decisions if decision.selected]
+            if selected:
+                self.store.record_recall(selected)
+                self.cache.clear()
+            return report
+        self.cache.set(key, report)
+        return report
+
+    def stats(self) -> dict[str, object]:
+        return self.store.stats() | {"cache_items": len(self.cache)}
+
+    def rebuild_indexes(self) -> dict[str, int]:
+        result = self.store.rebuild_indexes()
+        self.cache.clear()
+        return result
+
+    def close(self) -> None:
+        self.store.close()
+
+    def offload_context(
+        self,
+        snapshot_data: dict[str, Any],
+        session_id: str,
+        trigger: str = "manual",
+    ) -> str:
+        """
+        Saves the current agent state as a ContextSnapshot memory record.
+        """
+        from .schema import ContextSnapshot
+        snapshot = ContextSnapshot(
+            session_id=session_id,
+            snapshot_data=snapshot_data,
+            trigger=trigger,
+        )
+        record = snapshot.to_record()
+        # Ensure the session_id is in the content for FTS searchability
+        # ContextSnapshot.to_record currently only puts session_id in source.
+        # We add it to the content to ensure reload_context search works.
+        record.content = f"session_id:{session_id}\n{record.content}"
+        
+        from dataclasses import asdict
+        record_dict = asdict(record)
+        content = record_dict.pop("content")
+        saved = self.add(content, **record_dict)
+        return saved.id
+
+    def reload_context(
+        self,
+        session_id: str,
+        snapshot_id: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Retrieves the specified or most recent snapshot for the given session.
+        """
+        if snapshot_id:
+            record = self.get(snapshot_id)
+            if not record:
+                raise ValueError(f"Snapshot {snapshot_id} not found")
+        else:
+            # Latest is a recency question, not a relevance question: FTS
+            # ranking picks an arbitrary snapshot when timestamps tie.
+            record = self.store.latest_snapshot_record(session_id)
+            if not record:
+                raise ValueError(f"No snapshots found for session {session_id}")
+
+        # The content carries a session_id prefix for FTS searchability
+        raw_content = record.content
+        if raw_content.startswith(f"session_id:{session_id}\n"):
+            raw_content = raw_content[len(f"session_id:{session_id}\n"):]
+
+        return json.loads(raw_content)
+
+    def resonance_search(
+        self,
+        query: str,
+        *,
+        limit: int = 5,
+        resonance_hops: int = 2,
+    ) -> list[SearchResult]:
+        """
+        Enhanced retrieval using Memory Resonance logic.
+        1. Perform standard semantic search to find seed chunks.
+        2. Expand cluster using resonance weights.
+        3. Merge and rank results based on final resonance scores.
+        """
+        # 1. Get seed chunks via semantic search
+        seeds = self.search(query, limit=limit * 2)
+        if not seeds:
+            return []
+        
+        seed_ids = [res.record.id for res in seeds]
+        
+        # 2. Use ResonanceIndex to expand
+        from .memory_resonance import ERATripletIndex, MemoryChunk
+        idx = ERATripletIndex() 
+        
+        for res in seeds:
+            ts = datetime.fromisoformat(res.record.updated_at.replace('Z', '+00:00')).timestamp()
+            idx.add_chunk(MemoryChunk(id=res.record.id, text=res.record.content, timestamp=ts))
+            
+        resonant_ids = idx.resonance_cluster(seed_ids, hops=resonance_hops)
+        
+        final_results = []
+        id_map = {res.id: res for res in seeds}
+        for rid in resonant_ids:
+            if rid in id_map:
+                final_results.append(id_map[rid])
+            if len(final_results) >= limit:
+                break
+        return final_results