loop-memory 0.4.0__py3-none-any.whl

loop_memory/__init__.py

@@ -0,0 +1,62 @@
+"""Loop Engineering Memory System for Large Language Models.
+
+A zero-dependency framework that gives any LLM a persistent
+``Retrieve → Generate → Reflect → Store`` loop plus a tiered memory
+(short / long / episodic / procedural) and a SQLite-backed local store
+for cross-session recall.
+
+Optional extras:
+
+    pip install loop-memory[openai]    # OpenAIClient
+    pip install loop-memory[chroma]    # ChromaVectorStore
+    pip install loop-memory[sentence]  # SentenceTransformerEmbedder
+    pip install loop-memory[serve]     # FastAPI + uvicorn for the local UI
+    pip install loop-memory[all]       # everything
+"""
+
+from .backends.embedding import BaseEmbedder, HashingEmbedder, IdentityEmbedder
+from .backends.vector_store import (
+    ChromaVectorStore,
+    InMemoryVectorStore,
+    VectorStore,
+)
+from .engine.loop import LoopEngine, LoopResult
+from .llm.base import ChatHistory, EchoLLM, LLMClient, Message
+from .memory.types import (
+    EpisodicMemory,
+    LongTermMemory,
+    MemoryItem,
+    ProceduralMemory,
+    ShortTermMemory,
+)
+from .storage.sqlite_store import MemoryStore, StoredMemory, StoredSession
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # engine
+    "LoopEngine",
+    "LoopResult",
+    # memory
+    "MemoryItem",
+    "ShortTermMemory",
+    "LongTermMemory",
+    "EpisodicMemory",
+    "ProceduralMemory",
+    # llm
+    "LLMClient",
+    "EchoLLM",
+    "ChatHistory",
+    "Message",
+    # backends
+    "BaseEmbedder",
+    "HashingEmbedder",
+    "IdentityEmbedder",
+    "VectorStore",
+    "InMemoryVectorStore",
+    "ChromaVectorStore",
+    # storage
+    "MemoryStore",
+    "StoredMemory",
+    "StoredSession",
+]

loop_memory/backends/__init__.py

@@ -0,0 +1,13 @@
+"""Embedder + vector-store backends."""
+
+from .embedding import BaseEmbedder, HashingEmbedder, IdentityEmbedder
+from .vector_store import ChromaVectorStore, InMemoryVectorStore, VectorStore
+
+__all__ = [
+    "BaseEmbedder",
+    "HashingEmbedder",
+    "IdentityEmbedder",
+    "VectorStore",
+    "InMemoryVectorStore",
+    "ChromaVectorStore",
+]

loop_memory/backends/embedding.py

@@ -0,0 +1,82 @@
+"""Embedding backend abstractions.
+
+The library is zero-dependency by default. This module ships a
+``HashingEmbedder`` that produces deterministic bag-of-words style
+vectors — good enough for demos and tests. Real users plug in OpenAI,
+sentence-transformers, BGE, etc. via ``BaseEmbedder``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+
+from ..memory.types import MemoryItem
+
+_TOKEN_RE = re.compile(r"[\w]+", re.UNICODE)
+
+
+def _tokenize(text: str) -> list[str]:
+    return [t.lower() for t in _TOKEN_RE.findall(text)]
+
+
+class BaseEmbedder:
+    """Subclass and implement ``embed`` and ``embed_query``."""
+
+    dim: int = 0
+
+    def embed(self, items: list[MemoryItem]) -> list[list[float]]:
+        raise NotImplementedError
+
+    def embed_query(self, text: str) -> list[float]:
+        raise NotImplementedError
+
+
+class HashingEmbedder(BaseEmbedder):
+    """Deterministic hashed bag-of-words embedder.
+
+    Not semantically meaningful, but stable, dependency-free, and good
+    for tests. Useful when no real embedding model is available.
+    """
+
+    def __init__(self, dim: int = 256, ngram_range: tuple = (1, 2)) -> None:
+        self.dim = dim
+        self.ngram_range = ngram_range
+
+    def _vec(self, tokens: list[str]) -> list[float]:
+        vec = [0.0] * self.dim
+        for n in range(self.ngram_range[0], self.ngram_range[1] + 1):
+            for i in range(len(tokens) - n + 1):
+                gram = " ".join(tokens[i : i + n])
+                h = int(hashlib.md5(gram.encode("utf-8"), usedforsecurity=False).hexdigest(), 16)
+                idx = h % self.dim
+                sign = 1.0 if (h >> 8) & 1 else -1.0
+                vec[idx] += sign
+        norm = math.sqrt(sum(v * v for v in vec)) or 1e-12
+        return [v / norm for v in vec]
+
+    def embed(self, items: list[MemoryItem]) -> list[list[float]]:
+        return [self._vec(_tokenize(it.text)) for it in items]
+
+    def embed_query(self, text: str) -> list[float]:
+        return self._vec(_tokenize(text))
+
+    def embed_text(self, text: str) -> list[float]:
+        return self._vec(_tokenize(text))
+
+
+class IdentityEmbedder(BaseEmbedder):
+    """Pass-through embedder — store None; retrieval becomes score-only.
+
+    Useful when you don't want vector search at all and prefer ranking
+    by importance/recency alone.
+    """
+
+    dim = 0
+
+    def embed(self, items: list[MemoryItem]) -> list[list[float]]:
+        return [None]  # type: ignore[return-value]
+
+    def embed_query(self, text: str) -> None:  # type: ignore[override]
+        return None

loop_memory/backends/sentence_embedder.py

@@ -0,0 +1,30 @@
+"""Sentence-transformers backed embedder (optional dependency)."""
+
+from __future__ import annotations
+
+from ..memory.types import MemoryItem
+from .embedding import BaseEmbedder
+
+
+class SentenceTransformerEmbedder(BaseEmbedder):
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
+        try:
+            from sentence_transformers import SentenceTransformer  # type: ignore
+        except ImportError as e:
+            raise RuntimeError(
+                "sentence-transformers is not installed; "
+                "run `pip install loop-memory[sentence]`"
+            ) from e
+        self._model = SentenceTransformer(model_name)
+        self.dim = int(self._model.get_sentence_embedding_dimension())
+
+    def embed(self, items: list[MemoryItem]) -> list[list[float]]:
+        if not items:
+            return []
+        return [list(v) for v in self._model.encode([it.text for it in items])]
+
+    def embed_query(self, text: str) -> list[float]:
+        return list(self._model.encode([text])[0])
+
+    def embed_text(self, text: str) -> list[float]:
+        return self.embed_query(text)

loop_memory/backends/vector_store.py

@@ -0,0 +1,139 @@
+"""Pluggable vector-store abstraction.
+
+By default the loop engine keeps everything in-process via
+``HashingEmbedder``. For production workloads you can swap in any
+backend that implements ``VectorStore``: ChromaDB, FAISS, LanceDB,
+pgvector, etc.
+
+The store contract is intentionally minimal — add / search / delete —
+so wiring a new backend is a small subclass.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from ..memory.types import MemoryItem
+
+
+class VectorStore(Protocol):
+    def add(self, items: list[MemoryItem]) -> None: ...
+    def search(self, query_embedding: list[float], top_k: int = 5) -> list[MemoryItem]: ...
+    def delete(self, ids: Iterable[str]) -> int: ...
+    def count(self) -> int: ...
+
+
+@dataclass
+class InMemoryVectorStore:
+    """Reference implementation backed by a Python list.
+
+    Useful for unit tests and tiny personal agents. Not suitable for
+    corpora larger than a few thousand items.
+    """
+
+    _items: list[MemoryItem] = field(default_factory=list)
+
+    def add(self, items: list[MemoryItem]) -> None:
+        for it in items:
+            if it.embedding is None:
+                raise ValueError(f"MemoryItem {it.id!r} has no embedding")
+        self._items.extend(items)
+
+    def search(self, query_embedding: list[float], top_k: int = 5) -> list[MemoryItem]:
+        from ..memory.types import cosine_similarity
+
+        scored = [
+            (cosine_similarity(query_embedding, it.embedding or []), it)
+            for it in self._items
+            if it.embedding is not None
+        ]
+        scored.sort(key=lambda x: x[0], reverse=True)
+        return [it for _, it in scored[:top_k]]
+
+    def delete(self, ids: Iterable[str]) -> int:
+        ids_set = set(ids)
+        before = len(self._items)
+        self._items = [it for it in self._items if it.id not in ids_set]
+        return before - len(self._items)
+
+    def count(self) -> int:
+        return len(self._items)
+
+    def __iter__(self):
+        return iter(self._items)
+
+
+@dataclass
+class ChromaVectorStore:
+    """Optional ChromaDB backend. Imported lazily.
+
+    Install with::
+
+        pip install loop-memory[chroma]
+
+    Example::
+
+        store = ChromaVectorStore(collection="user_42")
+        engine = LoopEngine(llm=..., embedder=my_embedder, vector_store=store)
+    """
+
+    collection: str = "loop_memory"
+    persist_directory: str | None = None
+
+    def __post_init__(self) -> None:
+        try:
+            import chromadb  # type: ignore
+        except ImportError as e:
+            raise RuntimeError(
+                "chromadb is not installed; run `pip install loop-memory[chroma]`"
+            ) from e
+        client = (
+            chromadb.PersistentClient(path=self.persist_directory)
+            if self.persist_directory
+            else chromadb.Client()
+        )
+        self._collection = client.get_or_create_collection(name=self.collection)
+
+    def add(self, items: list[MemoryItem]) -> None:
+        for it in items:
+            if it.embedding is None:
+                raise ValueError(f"MemoryItem {it.id!r} has no embedding")
+            self._collection.add(
+                ids=[it.id],
+                embeddings=[it.embedding],
+                documents=[it.text],
+                metadatas=[{"kind": it.kind, "importance": it.importance}],
+            )
+
+    def search(self, query_embedding: list[float], top_k: int = 5) -> list[MemoryItem]:
+        res = self._collection.query(
+            query_embeddings=[query_embedding],
+            n_results=top_k,
+        )
+        out: list[MemoryItem] = []
+        ids = (res.get("ids") or [[]])[0]
+        docs = (res.get("documents") or [[]])[0]
+        metas = (res.get("metadatas") or [[]])[0]
+        for i, _id in enumerate(ids):
+            meta = metas[i] if i < len(metas) else {}
+            out.append(
+                MemoryItem(
+                    id=_id,
+                    text=docs[i] if i < len(docs) else "",
+                    importance=float(meta.get("importance", 0.5)),
+                    kind=str(meta.get("kind", "fact")),
+                )
+            )
+        return out
+
+    def delete(self, ids: Iterable[str]) -> int:
+        ids_list = list(ids)
+        if not ids_list:
+            return 0
+        self._collection.delete(ids=ids_list)
+        return len(ids_list)
+
+    def count(self) -> int:
+        return int(self._collection.count())

loop_memory/cli/_common.py

@@ -0,0 +1,68 @@
+"""Shared helpers for CLI commands.
+
+Kept in a single tiny module so the per-command files can stay
+focused on dispatch logic instead of repeating flag parsing and
+default paths.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from ..backends.embedding import HashingEmbedder
+from ..engine.loop import LoopEngine
+from ..llm.base import EchoLLM
+
+DEFAULT_DB = os.environ.get(
+    "LOOP_MEMORY_DB",
+    str(Path.home() / ".loop_memory" / "loop_memory.db"),
+)
+
+
+def default_db_path() -> str:
+    """Resolve the DB path at call time (not import time).
+
+    Use this instead of the module-level ``DEFAULT_DB`` whenever the
+    caller may run after the test suite (or any embedded host) has
+    changed ``$LOOP_MEMORY_DB``.
+    """
+    return os.environ.get(
+        "LOOP_MEMORY_DB",
+        str(Path.home() / ".loop_memory" / "loop_memory.db"),
+    )
+
+
+
+def make_engine(db_path: str | None = None) -> LoopEngine:
+    """Build a LoopEngine with the default echo LLM + hashing embedder.
+
+    Used by ``chat`` and any other command that drives the engine
+    end-to-end without an external LLM.
+    """
+    return LoopEngine(llm=EchoLLM(), embedder=HashingEmbedder(dim=128))
+
+
+def parse_int_flag(args: list, name: str, default: int) -> tuple[int, list]:
+    """Pop ``--name <int>`` from ``args`` if present.
+
+    Returns the parsed integer (or ``default``) plus the remaining
+    args. Non-integer values fall back to ``default`` so we never
+    crash the whole command on a typo.
+    """
+    if name in args:
+        i = args.index(name)
+        if i + 1 < len(args):
+            try:
+                v = int(args[i + 1])
+                return v, args[:i] + args[i + 2:]
+            except ValueError:
+                pass
+    return default, list(args)
+
+
+def die(msg: str, code: int = 2) -> int:
+    """Print ``msg`` to stderr and return ``code``."""
+    print(msg, file=sys.stderr)
+    return code

loop_memory/cli/commands/__init__.py

@@ -0,0 +1,13 @@
+"""CLI command implementations.
+
+Each module in this package exports a small ``run(args) -> int``
+function. ``cli.main`` is responsible only for dispatch.
+
+Modules are grouped by concern:
+
+* ``read``   — read-only commands (chat, stats, recall, ask, export, inject)
+* ``write``  — mutation commands (ingest, flush, consolidate, rescore)
+* ``serve``  — server / hook / mcp commands
+* ``hooks``  — install-hooks auto-config
+* ``graph``  — knowledge graph commands
+"""

loop_memory/cli/commands/cognitive.py

@@ -0,0 +1,205 @@
+"""CLI commands for the Universal Agent Memory v7 surface.
+
+* ``loop-memory cognitive-sleep`` — run a sweep, optionally apply.
+* ``loop-memory audit``          — read the audit trail.
+* ``loop-memory export``         — write a MEMORY.md bundle.
+* ``loop-memory import``         — re-hydrate a bundle.
+* ``loop-memory fork``           — snapshot the wiki.
+* ``loop-memory graph-edge``     — push a semantic relation.
+* ``loop-memory subgraph``       — print a small subgraph.
+
+All commands accept ``--db PATH`` to point at a non-default store
+(handy in tests). They print JSON so a shell pipeline can consume
+the output.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from ...storage.sqlite_store import MemoryStore
+from .._common import DEFAULT_DB, default_db_path
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="loop-memory (v7)", add_help=True)
+    p.add_argument("--db", default=DEFAULT_DB,
+                   help=f"Path to the SQLite store (default {DEFAULT_DB})")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    cs = sub.add_parser("cognitive-sleep", help="Run a cognitive sweep")
+    cs.add_argument("--apply", action="store_true",
+                    help="Actually delete the suggested memories")
+    cs.add_argument("--stale-days", type=int, default=90)
+    cs.add_argument("--min-score", type=float, default=0.2)
+    cs.add_argument("--min-importance", type=float, default=0.3)
+    cs.add_argument("--low-value", type=float, default=0.3)
+    cs.add_argument("--merge-threshold", type=float, default=0.92)
+    cs.add_argument("--limit", type=int, default=1000)
+
+    au = sub.add_parser("audit", help="Read the cognitive audit trail")
+    au.add_argument("--kind", default=None)
+    au.add_argument("--action", default=None)
+    au.add_argument("--limit", type=int, default=200)
+
+    ex = sub.add_parser("export", help="Write a MEMORY.md bundle")
+    ex.add_argument("out_dir")
+    ex.add_argument("--agent-id", default=None)
+    ex.add_argument("--user-id", default=None)
+    ex.add_argument("--scope", default="global")
+    ex.add_argument("--min-importance", type=float, default=0.0)
+
+    im = sub.add_parser("import", help="Re-hydrate a MEMORY.md bundle")
+    im.add_argument("in_dir")
+    im.add_argument("--agent-id", default=None)
+    im.add_argument("--user-id", default=None)
+    im.add_argument("--dry-run", action="store_true")
+
+    fk = sub.add_parser("fork", help="Snapshot every wiki page")
+    fk.add_argument("--branch-tag", default=None)
+
+    ge = sub.add_parser("graph-edge", help="Push a semantic relation")
+    ge.add_argument("src")
+    ge.add_argument("dst")
+    ge.add_argument("--kind", default="relates_to")
+    ge.add_argument("--weight", type=float, default=0.5)
+    ge.add_argument("--evidence-id", default=None)
+
+    sg = sub.add_parser("subgraph", help="Print a small subgraph")
+    sg.add_argument("query")
+    sg.add_argument("--max-nodes", type=int, default=32)
+    sg.add_argument("--max-edges", type=int, default=64)
+
+    sub.add_parser("graph-rebuild", help="Rebuild the entity graph")
+
+    rc = sub.add_parser(
+        "wiki-reclassify-legacy",
+        help=("Re-classify legacy wiki pages whose auto_classification is NULL; "
+              "downgrade non-universal-security pages to per-source scope."))
+    rc.add_argument("--batch", type=int, default=500,
+                    help="Maximum rows to scan (default 500)")
+    rc.add_argument("--dry-run", action="store_true",
+                    help="Report what would change without persisting")
+
+    return p
+
+
+def _emit(d) -> int:
+    print(json.dumps(d, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+def run_cognitive_sleep(args: list) -> int:
+    p = _build_parser()
+    ns = p.parse_args(["--db", os.environ.get("LOOP_MEMORY_DB", DEFAULT_DB),
+                        "cognitive-sleep", *args])
+    s = MemoryStore(ns.db)
+    from ...jobs.cognitive import cognitive_sleep
+    rpt = cognitive_sleep(
+        s, apply=ns.apply,
+        stale_days=ns.stale_days, min_score=ns.min_score,
+        min_importance=ns.min_importance, low_value=ns.low_value,
+        merge_threshold=ns.merge_threshold, limit=ns.limit,
+    )
+    return _emit(rpt.to_dict())
+
+
+def run_audit(args: list) -> int:
+    p = _build_parser()
+    db = os.environ.get("LOOP_MEMORY_DB", DEFAULT_DB)
+    ns = p.parse_args(["--db", db, "audit", *args])
+    s = MemoryStore(ns.db)
+    return _emit({"rows": s.list_audit(kind=ns.kind, action=ns.action, limit=ns.limit)})
+
+
+def run_export(args: list) -> int:
+    p = _build_parser()
+    db = os.environ.get("LOOP_MEMORY_DB", DEFAULT_DB)
+    ns = p.parse_args(["--db", db, "export", *args])
+    s = MemoryStore(ns.db)
+    from ...export import export_bundle
+    r = export_bundle(s, ns.out_dir, agent_id=ns.agent_id, user_id=ns.user_id,
+                      scope=ns.scope, min_importance=ns.min_importance)
+    return _emit(r.to_dict())
+
+
+def run_import(args: list) -> int:
+    p = _build_parser()
+    db = os.environ.get("LOOP_MEMORY_DB", DEFAULT_DB)
+    ns = p.parse_args(["--db", db, "import", *args])
+    s = MemoryStore(ns.db)
+    from ...export import import_bundle
+    r = import_bundle(s, ns.in_dir, agent_id=ns.agent_id, user_id=ns.user_id,
+                      dry_run=ns.dry_run)
+    return _emit(r.to_dict())
+
+
+def run_fork(args: list) -> int:
+    p = _build_parser()
+    db = os.environ.get("LOOP_MEMORY_DB", DEFAULT_DB)
+    ns = p.parse_args(["--db", db, "fork", *args])
+    s = MemoryStore(ns.db)
+    from ...export import fork_snapshot
+    return _emit(fork_snapshot(s, branch_tag=ns.branch_tag))
+
+
+def run_graph_edge(args: list) -> int:
+    p = _build_parser()
+    db = os.environ.get("LOOP_MEMORY_DB", DEFAULT_DB)
+    ns = p.parse_args(["--db", db, "graph-edge", *args])
+    s = MemoryStore(ns.db)
+    from ...jobs.graph import upsert_semantic_edge
+    info = upsert_semantic_edge(
+        s, ns.src, ns.dst, kind=ns.kind, weight=ns.weight,
+        evidence_id=ns.evidence_id,
+    )
+    return _emit(info)
+
+
+def run_subgraph(args: list) -> int:
+    p = _build_parser()
+    db = os.environ.get("LOOP_MEMORY_DB", DEFAULT_DB)
+    ns = p.parse_args(["--db", db, "subgraph", *args])
+    s = MemoryStore(ns.db)
+    from ...jobs.graph import subgraph_for
+    sg = subgraph_for(s, ns.query, max_nodes=ns.max_nodes, max_edges=ns.max_edges)
+    return _emit(sg.to_dict())
+
+
+def run_graph_rebuild(args: list) -> int:
+    p = _build_parser()
+    db = os.environ.get("LOOP_MEMORY_DB", DEFAULT_DB)
+    ns = p.parse_args(["--db", db, "graph-rebuild", *args])
+    s = MemoryStore(ns.db)
+    from ...graph.build import KnowledgeGraph
+    KnowledgeGraph(s).rebuild(clear=True)
+    n = s.rebuild_entity_mentions()
+    return _emit({"entity_mentions": n})
+
+
+def run_wiki_reclassify_legacy(args: list) -> int:
+    p = _build_parser()
+    db = os.environ.get("LOOP_MEMORY_DB", DEFAULT_DB)
+    ns = p.parse_args(["--db", db, "wiki-reclassify-legacy", *args])
+    s = MemoryStore(ns.db)
+    from ...wiki import reclassify_legacy_pages
+    if ns.dry_run:
+        pages = s.list_wiki_pages(limit=ns.batch)
+        legacy = [
+            p for p in pages
+            if (p.get("scope") or "global") == "global"
+            and p.get("auto_classification") is None
+        ]
+        return _emit({
+            "dry_run": True,
+            "scanned": len(pages),
+            "legacy_global": len(legacy),
+            "items": [{"slug": p["slug"], "title": p.get("title")}
+                      for p in legacy],
+        })
+    summary = reclassify_legacy_pages(s, batch=ns.batch)
+    return _emit(summary)