memoryagent-lib 0.1.1__py3-none-any.whl

memoryagent/__init__.py

@@ -0,0 +1,35 @@
+from memoryagent.config import MemorySystemConfig
+from memoryagent.models import (
+    ConfidenceReport,
+    MemoryBlock,
+    MemoryEvent,
+    MemoryItem,
+    MemoryQuery,
+    MemoryType,
+    RetrievalPlan,
+)
+from memoryagent.policy import (
+    ConversationMemoryPolicy,
+    HeuristicMemoryPolicy,
+    MemoryDecision,
+    MemoryRoutingPolicy,
+    RoutingDecision,
+)
+from memoryagent.system import MemorySystem
+
+__all__ = [
+    "MemorySystem",
+    "MemorySystemConfig",
+    "MemoryEvent",
+    "MemoryItem",
+    "MemoryQuery",
+    "MemoryType",
+    "MemoryBlock",
+    "RetrievalPlan",
+    "ConfidenceReport",
+    "ConversationMemoryPolicy",
+    "HeuristicMemoryPolicy",
+    "MemoryDecision",
+    "MemoryRoutingPolicy",
+    "RoutingDecision",
+]

memoryagent/confidence.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import List
+
+from memoryagent.models import ConfidenceReport, MemoryQuery, ScoredMemory
+from memoryagent.utils import clamp, safe_div, unique_tokens
+
+
+def _semantic_relevance(results: List[ScoredMemory]) -> float:
+    if not results:
+        return 0.0
+    top_scores = [r.score for r in results[:5]]
+    return sum(top_scores) / len(top_scores)
+
+
+def _coverage(query: MemoryQuery, results: List[ScoredMemory]) -> float:
+    query_tokens = unique_tokens(query.text)
+    if not query_tokens:
+        return 0.0
+    covered = set()
+    for item in results[:5]:
+        covered |= unique_tokens(item.item.text())
+    return safe_div(len(query_tokens & covered), len(query_tokens))
+
+
+def _temporal_fit(results: List[ScoredMemory]) -> float:
+    if not results:
+        return 0.0
+    now = datetime.now(timezone.utc)
+    scores = []
+    for item in results[:5]:
+        age_days = max(0.0, (now - item.item.created_at).total_seconds() / 86400)
+        scores.append(1.0 / (1.0 + age_days))
+    return sum(scores) / len(scores)
+
+
+def _authority(results: List[ScoredMemory]) -> float:
+    if not results:
+        return 0.0
+    scores = [0.5 * r.item.authority + 0.5 * r.item.stability for r in results[:5]]
+    return sum(scores) / len(scores)
+
+
+def _consistency(results: List[ScoredMemory]) -> float:
+    if len(results) < 2:
+        return 0.5
+    tag_sets = [set(r.item.tags) for r in results[:5] if r.item.tags]
+    if not tag_sets:
+        return 0.4
+    overlap = set.intersection(*tag_sets) if len(tag_sets) > 1 else tag_sets[0]
+    union = set.union(*tag_sets) if len(tag_sets) > 1 else tag_sets[0]
+    return safe_div(len(overlap), len(union))
+
+
+def evaluate_confidence(query: MemoryQuery, results: List[ScoredMemory]) -> ConfidenceReport:
+    semantic = _semantic_relevance(results)
+    coverage = _coverage(query, results)
+    temporal = _temporal_fit(results)
+    authority = _authority(results)
+    consistency = _consistency(results)
+
+    total = clamp(0.35 * semantic + 0.2 * coverage + 0.2 * temporal + 0.15 * authority + 0.1 * consistency)
+
+    if total >= 0.75:
+        recommendation = "accept"
+    elif total >= 0.6:
+        recommendation = "escalate_archive"
+    elif total >= 0.45:
+        recommendation = "fetch_cold"
+    else:
+        recommendation = "uncertain"
+
+    return ConfidenceReport(
+        total=total,
+        semantic_relevance=semantic,
+        coverage=coverage,
+        temporal_fit=temporal,
+        authority=authority,
+        consistency=consistency,
+        recommendation=recommendation,
+    )

memoryagent/config.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from memoryagent.models import RetrievalPlan
+
+
+class ConsolidationConfig(BaseModel):
+    archive_on_flush: bool = True
+    semantic_min_count: int = 2
+    perceptual_summary_limit: int = 5
+
+
+class MemorySystemConfig(BaseModel):
+    """System-wide configuration with sane local defaults."""
+
+    working_ttl_seconds: int = 3600
+    retrieval_plan: RetrievalPlan = Field(default_factory=RetrievalPlan)
+    consolidation: ConsolidationConfig = Field(default_factory=ConsolidationConfig)
+    cold_store_path: Path = Field(default_factory=lambda: Path(".memoryagent_cold"))
+    metadata_db_path: Path = Field(default_factory=lambda: Path(".memoryagent_hot.sqlite"))
+    feature_db_path: Path = Field(default_factory=lambda: Path(".memoryagent_features.sqlite"))
+    vector_db_path: Path = Field(default_factory=lambda: Path(".memoryagent_vectors.sqlite"))
+    vector_dim: int = 384
+    use_sqlite_vec: bool = False
+    sqlite_vec_extension_path: Optional[Path] = None
+    archive_index_path: Optional[Path] = None
+
+    def resolved_archive_path(self) -> Path:
+        if self.archive_index_path is not None:
+            return self.archive_index_path
+        return self.cold_store_path / "archive_index.json"

memoryagent/consolidation.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from memoryagent.workers import ConsolidationWorker
+
+__all__ = ["ConsolidationWorker"]

memoryagent/examples/export_memory.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any, Dict, List
+
+ROOT = Path(__file__).resolve().parents[2]
+COLD_ROOT = ROOT / ".memoryagent_cold"
+HOT_DB = ROOT / ".memoryagent_hot.sqlite"
+FEATURE_DB = ROOT / ".memoryagent_features.sqlite"
+ARCHIVE_INDEX = COLD_ROOT / "archive_index.json"
+
+
+def load_hot() -> List[Dict[str, Any]]:
+    if not HOT_DB.exists():
+        return []
+    with sqlite3.connect(HOT_DB) 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"
+        ).fetchall()
+    items = []
+    for row in rows:
+        (
+            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
+        items.append(
+            {
+                "id": item_id,
+                "type": 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": created_at,
+                "updated_at": updated_at,
+                "last_accessed": last_accessed,
+                "tier": tier,
+                "pointer": json.loads(pointer_json) if pointer_json else {},
+                "ttl_seconds": ttl_seconds,
+                "confidence": confidence,
+                "authority": authority,
+                "stability": stability,
+            }
+        )
+    return items
+
+
+def load_features() -> List[Dict[str, Any]]:
+    if not FEATURE_DB.exists():
+        return []
+    with sqlite3.connect(FEATURE_DB) as conn:
+        rows = conn.execute("SELECT owner, created_at, payload_json FROM features").fetchall()
+    features = []
+    for owner, created_at, payload_json in rows:
+        features.append(
+            {
+                "owner": owner,
+                "created_at": created_at,
+                "payload": json.loads(payload_json),
+            }
+        )
+    return features
+
+
+def load_cold_records() -> List[Dict[str, Any]]:
+    if not COLD_ROOT.exists():
+        return []
+    records = []
+    records_root = COLD_ROOT / "records"
+    if not records_root.exists():
+        return []
+    for path in records_root.rglob("*.json"):
+        try:
+            records.append({"path": str(path.relative_to(ROOT)), "payload": json.loads(path.read_text())})
+        except Exception:
+            continue
+    return records
+
+
+def load_archive_index() -> Dict[str, Any]:
+    if not ARCHIVE_INDEX.exists():
+        return {}
+    return json.loads(ARCHIVE_INDEX.read_text())
+
+
+def get_memory_payload() -> Dict[str, Any]:
+    return {
+        "hot_items": load_hot(),
+        "features": load_features(),
+        "cold_records": load_cold_records(),
+        "archive_index": load_archive_index(),
+    }
+
+
+__all__ = ["get_memory_payload"]

memoryagent/examples/memory_api_server.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import json
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+import os
+from memoryagent.examples.export_memory import get_memory_payload
+from uuid import uuid4
+
+from memoryagent import (
+    HeuristicMemoryPolicy,
+    MemoryItem,
+    MemoryRoutingPolicy,
+    MemorySystem,
+    MemorySystemConfig,
+    MemoryType,
+)
+from memoryagent.utils import hash_embed, tokenize
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+try:
+    from openai import OpenAI
+except Exception:
+    OpenAI = None
+
+_history = {}
+
+
+def _get_openai_client():
+    if OpenAI is None:
+        raise RuntimeError("openai package is not installed")
+    return OpenAI()
+
+
+def _openai_embedder(client, model: str, dim: int):
+    def _embed(text: str):
+        try:
+            response = client.embeddings.create(model=model, input=text)
+            return response.data[0].embedding
+        except Exception:
+            return hash_embed(text, dim)
+
+    return _embed
+
+
+def _history_entry_text(entry) -> str:
+    if isinstance(entry, str):
+        return entry
+    if isinstance(entry, dict):
+        if "user" in entry and "assistant" in entry:
+            return f"User: {entry['user']} Assistant: {entry['assistant']}"
+        if "role" in entry and "text" in entry:
+            return f"{entry['role']}: {entry['text']}"
+    return str(entry)
+
+
+def _get_memory_system():
+    model = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+    embedding_model = os.environ.get("OPENAI_EMBED_MODEL", "text-embedding-3-small")
+    vector_dim = int(os.environ.get("OPENAI_EMBED_DIM", "1536"))
+
+    config = MemorySystemConfig(
+        use_sqlite_vec=True,
+        vector_dim=vector_dim,
+        sqlite_vec_extension_path=os.environ.get("SQLITE_VEC_PATH"),
+    )
+    client = _get_openai_client()
+    memory = MemorySystem(
+        config=config,
+        embedding_fn=_openai_embedder(client, embedding_model, config.vector_dim),
+    )
+    return memory, client, model
+
+
+class MemoryAPIHandler(BaseHTTPRequestHandler):
+    def _send_json(self, payload, status=200):
+        data = json.dumps(payload, ensure_ascii=True).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.end_headers()
+        self.wfile.write(data)
+
+    def do_GET(self):
+        if self.path.startswith("/api/memory"):
+            payload = get_memory_payload()
+            owner = None
+            if "?" in self.path:
+                _, query = self.path.split("?", 1)
+                for part in query.split("&"):
+                    if part.startswith("owner="):
+                        owner = part.split("=", 1)[1]
+                        break
+            if owner:
+                payload["hot_items"] = [item for item in payload.get("hot_items", []) if item.get("owner") == owner]
+                payload["features"] = [
+                    item for item in payload.get("features", []) if item.get("owner") == owner
+                ]
+                payload["cold_records"] = [
+                    item for item in payload.get("cold_records", [])
+                    if f"/{owner}/" in item.get("path", "")
+                ]
+            self._send_json(payload)
+            return
+        if self.path in {"/", "/memory_viz.html"}:
+            html_path = Path(__file__).resolve().parent / "memory_viz.html"
+            if not html_path.exists():
+                self.send_error(404, "memory_viz.html not found")
+                return
+            data = html_path.read_bytes()
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+            return
+        self.send_error(404, "Not found")
+
+    def do_POST(self):
+        if self.path not in {"/api/chat", "/api/chat/"}:
+            self.send_error(404, "Not found")
+            return
+        length = int(self.headers.get("Content-Length", "0"))
+        body = self.rfile.read(length).decode("utf-8") if length else "{}"
+        try:
+            payload = json.loads(body)
+        except Exception:
+            self.send_error(400, "Invalid JSON")
+            return
+
+        owner = payload.get("owner", "user-001")
+        message = payload.get("message", "").strip()
+        if not message:
+            self.send_error(400, "Missing message")
+            return
+
+        try:
+            memory, client, model = _get_memory_system()
+        except Exception as exc:
+            self.send_error(500, str(exc))
+            return
+
+        session = _history.setdefault(owner, {"turns": [], "working_id": str(uuid4())})
+        history = session["turns"]
+        bundle = memory.retrieve(message, owner=owner)
+        context_blocks = []
+        token_budget = memory.config.retrieval_plan.max_context_tokens
+        used_tokens = 0
+        for block in bundle.blocks:
+            block_text = f"- [{block.memory_type}] {block.text}"
+            if not isinstance(block_text, str):
+                block_text = str(block_text)
+            block_tokens = len(tokenize(block_text))
+            if used_tokens + block_tokens > token_budget:
+                break
+            context_blocks.append(block_text)
+            used_tokens += block_tokens
+        memory_context = "\n".join(str(item) for item in context_blocks) if context_blocks else "None."
+        recent_turns = history[-6:]
+        history_text_entries = [_history_entry_text(entry) for entry in recent_turns]
+        history_text = "\n".join(history_text_entries) if history_text_entries else "None."
+        prompt = (
+            "You are a helpful assistant.\n"
+            "Use the following memory context and recent chat history if relevant.\n"
+            f"Memory context:\n{memory_context}\n\n"
+            f"Recent chat:\n{history_text}\n\n"
+            f"User: {message}\n"
+            "Assistant:"
+        )
+        response = client.responses.create(model=model, input=prompt)
+        assistant_message = response.output_text
+
+        history.append({"user": message, "assistant": assistant_message})
+
+        working_item = MemoryItem(
+            id=session["working_id"],
+            type=MemoryType.WORKING,
+            owner=owner,
+            summary=f"Session transcript ({len(history)} turns)",
+            content={"turns": history},
+            tags=["conversation", "session-log"],
+            ttl_seconds=memory.config.working_ttl_seconds,
+            confidence=0.6,
+        )
+        memory.write(working_item)
+
+        policy = HeuristicMemoryPolicy()
+        routing_policy = MemoryRoutingPolicy()
+        history_for_policy = [_history_entry_text(entry) for entry in history]
+        decision = policy.should_store(owner, history_for_policy, message, assistant_message)
+        event = policy.to_event(owner, decision)
+        if event:
+            routing = routing_policy.route(event.to_item())
+            if routing.write_hot or routing.write_vector or routing.write_features:
+                memory.write(event)
+
+        self._send_json(
+            {
+                "reply": assistant_message,
+                "trace": {
+                    "steps": bundle.trace.steps,
+                    "escalations": bundle.trace.escalations,
+                    "sources": bundle.trace.sources,
+                    "confidence": bundle.confidence.total,
+                },
+            }
+        )
+
+
+def main() -> None:
+    server = HTTPServer(("127.0.0.1", 8000), MemoryAPIHandler)
+    print("Serving memory API at http://127.0.0.1:8000/api/memory")
+    print("Open http://127.0.0.1:8000/memory_viz.html")
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

memoryagent/examples/minimal.py

@@ -0,0 +1,47 @@
+from memoryagent import MemoryEvent, MemorySystem
+
+
+def main() -> None:
+    memory = MemorySystem()
+
+    owner = "session-123"
+    memory.write(
+        MemoryEvent(
+            content="User prefers concise summaries about climate policy.",
+            type="semantic",
+            owner=owner,
+            tags=["preference", "summary"],
+            confidence=0.7,
+            stability=0.8,
+        )
+    )
+
+    memory.write(
+        MemoryEvent(
+            content="Discussed EU carbon border adjustment mechanism.",
+            type="episodic",
+            owner=owner,
+            tags=["eu", "policy"],
+        )
+    )
+
+    memory.write_perceptual(
+        {
+            "content": "Audio signal indicates frustration when asked about timelines.",
+            "owner": owner,
+            "tags": ["sentiment", "frustration"],
+        }
+    )
+
+    bundle = memory.retrieve("What policy topics did we cover?", owner=owner)
+
+    print("Confidence:", bundle.confidence.total)
+    print("Blocks:")
+    for block in bundle.blocks:
+        print(f"- [{block.memory_type}] {block.text}")
+
+    memory.flush(owner)
+
+
+if __name__ == "__main__":
+    main()

memoryagent/examples/openai_agent.py

@@ -0,0 +1,137 @@
+import os
+import time
+from uuid import uuid4
+from typing import List
+
+from openai import OpenAI
+
+from memoryagent import (
+    HeuristicMemoryPolicy,
+    MemoryEvent,
+    MemoryItem,
+    MemoryRoutingPolicy,
+    MemorySystem,
+    MemorySystemConfig,
+    MemoryType,
+)
+from memoryagent.utils import hash_embed, tokenize
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def openai_embedder(client: OpenAI, model: str, dim: int):
+    def _embed(text: str):
+        try:
+            response = client.embeddings.create(model=model, input=text)
+            return response.data[0].embedding
+        except Exception:
+            return hash_embed(text, dim)
+
+    return _embed
+
+
+def main() -> None:
+    # Requires: pip install openai sqlite-vec (or set SQLITE_VEC_PATH)
+    client = OpenAI()
+
+    model = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+    embedding_model = os.environ.get("OPENAI_EMBED_MODEL", "text-embedding-3-small")
+    vector_dim = int(os.environ.get("OPENAI_EMBED_DIM", "1536"))
+
+    config = MemorySystemConfig(
+        use_sqlite_vec=True,
+        vector_dim=vector_dim,
+        sqlite_vec_extension_path=os.environ.get("SQLITE_VEC_PATH"),
+    )
+    memory = MemorySystem(
+        config=config,
+        embedding_fn=openai_embedder(client, embedding_model, config.vector_dim),
+    )
+    policy = HeuristicMemoryPolicy()
+    routing_policy = MemoryRoutingPolicy()
+    session_working_id = str(uuid4())
+
+    owner = "user-001"
+    history: List[str] = []
+
+    while True:
+        user_message = input("User: ").strip()
+        if user_message.lower() in {"exit", "quit"}:
+            break
+
+        turn_start = time.time()
+        bundle = memory.retrieve(user_message, owner=owner)
+        print(
+            f"[trace] retrieve count={len(bundle.blocks)} confidence={bundle.confidence.total:.2f} tiers={bundle.used_tiers}"
+        )
+        if bundle.trace.escalations:
+            print(f"[trace] escalations={bundle.trace.escalations}")
+        if bundle.trace.steps:
+            print(f"[trace] steps={bundle.trace.steps}")
+        if bundle.trace.sources:
+            print(f"[trace] sources={bundle.trace.sources}")
+        context_blocks = []
+        token_budget = memory.config.retrieval_plan.max_context_tokens
+        used_tokens = 0
+        for block in bundle.blocks:
+            block_text = f"- [{block.memory_type}] {block.text}"
+            block_tokens = len(tokenize(block_text))
+            if used_tokens + block_tokens > token_budget:
+                break
+            context_blocks.append(block_text)
+            used_tokens += block_tokens
+        memory_context = "\n".join(context_blocks) if context_blocks else "None."
+        recent_turns = history[-6:]
+        history_text = "\n".join(recent_turns) if recent_turns else "None."
+        prompt = (
+            "You are a helpful assistant.\n"
+            "Use the following memory context and recent chat history if relevant.\n"
+            f"Memory context:\n{memory_context}\n\n"
+            f"Recent chat:\n{history_text}\n\n"
+            f"User: {user_message}\n"
+            "Assistant:"
+        )
+
+        response = client.responses.create(
+            model=model,
+            input=prompt,
+        )
+        assistant_message = response.output_text
+        print(f"[trace] llm_latency_ms={(time.time() - turn_start) * 1000:.0f}")
+        print(f"Assistant: {assistant_message}")
+
+        history.append(f"User: {user_message}")
+        history.append(f"Assistant: {assistant_message}")
+
+        turns = [
+            {"role": "user", "text": entry.replace("User: ", "")}
+            if entry.startswith("User: ")
+            else {"role": "assistant", "text": entry.replace("Assistant: ", "")}
+            for entry in history
+        ]
+        working_item = MemoryItem(
+            id=session_working_id,
+            type=MemoryType.WORKING,
+            owner=owner,
+            summary=f"Session transcript ({len(turns)} turns)",
+            content={"turns": turns},
+            tags=["conversation", "session-log"],
+            ttl_seconds=memory.config.working_ttl_seconds,
+            confidence=0.6,
+        )
+        memory.write(working_item)
+
+        decision = policy.should_store(owner, history, user_message, assistant_message)
+        print(decision)
+        event = policy.to_event(owner, decision)
+        if event:
+            routing = routing_policy.route(event.to_item())
+            print(f"[memory] store={decision.store} routing={routing.reasons}")
+            memory.write(event)
+
+    memory.flush(owner)
+
+
+if __name__ == "__main__":
+    main()