loop-memory 0.4.0__py3-none-any.whl

loop_memory/cli/main.py

@@ -0,0 +1,115 @@
+"""CLI for Loop Memory.
+
+Usage:
+
+    loop-memory chat              # REPL with echo LLM
+    loop-memory stats             # counters
+    loop-memory recall <text>     # show top memories
+    loop-memory ingest codex      # ingest local Codex transcripts
+    loop-memory ingest claude     # ingest local Claude Code transcripts
+    loop-memory ingest hermes     # ingest Hermes transcripts
+    loop-memory consolidate       # rescore + GC + dedupe
+    loop-memory rescore [--half-life 30]
+    loop-memory serve [--port 7767] # start the local web UI
+    loop-memory mcp                # stdio MCP server (for codex/claude/hermes)
+    loop-memory inject [query]     # dump long-term context block (for SessionStart hooks)
+    loop-memory install-hooks      # auto-write MCP + SessionStart hooks for known clients
+    loop-memory consolidate-now    # ask the running server to trigger a pass right now
+    loop-memory export             # legacy markdown export (no positional path)
+    loop-memory digest [--out PATH] # compact knowledge digest for AGENTS.md (≤ max-chars bytes)
+    loop-memory ask "what about…"  # print a paste-ready context block for any LLM client
+    loop-memory cognitive-sleep [--apply]  # dry-run / apply cognitive sweep (v7)
+    loop-memory audit [--kind X] [--action Y]  # read the cognitive audit trail
+    loop-memory export <out_dir>  # write a MEMORY.md bundle (v7)
+    loop-memory export-bundle <out_dir>  # explicit v7 bundle alias
+    loop-memory import <in_dir>   # re-hydrate a bundle
+    loop-memory fork [--branch-tag T]  # snapshot every wiki page
+    loop-memory graph-edge <src> <dst> [--kind K] [--weight W]  # push a relation
+    loop-memory subgraph <query>  # print a small subgraph
+    loop-memory graph-rebuild  # rebuild entities + entity_mentions
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .commands import cognitive as cognitive_cmd
+from .commands import diag as diag_cmd
+from .commands import graph as graph_cmd
+from .commands import hooks as hooks_cmd
+from .commands import read as read_cmd
+from .commands import serve as serve_cmd
+from .commands import write as write_cmd
+
+# Backwards-compatible re-exports. Earlier tests imported these
+# private symbols from this module; keep the names available so
+# external code doesn't break after the 0.3.0 split.
+_upsert_block = hooks_cmd._upsert_block
+cmd_inject = read_cmd.run_inject
+
+
+def _run_export(args: list[str]) -> int:
+    """Keep the legacy markdown export and expose the v7 bundle export.
+
+    A positional output directory selects the v7 bundle. The historical
+    ``--out`` / ``--q`` form remains available so existing scripts keep
+    producing a single markdown file.
+    """
+    if not args or any(flag in args for flag in ("--out", "--q")):
+        return read_cmd.run_export(args)
+    return cognitive_cmd.run_export(args)
+
+
+# Dispatch table: command name -> (callable, optional module doc).
+# Each module's ``run_<name>`` function takes ``args: list[str]`` and
+# returns an integer exit code. Keep the keys matching the docstring
+# at the top of this file.
+COMMANDS = {
+    "chat": read_cmd.run_chat,
+    "stats": read_cmd.run_stats,
+    "recall": read_cmd.run_recall,
+    "ingest": write_cmd.run_ingest,
+    "consolidate": write_cmd.run_consolidate,
+    "consolidate-now": write_cmd.run_consolidate_now,
+    "export": _run_export,
+    "digest": read_cmd.run_digest,
+    "ask": read_cmd.run_ask,
+    "rescore": write_cmd.run_rescore,
+    "serve": serve_cmd.run_serve,
+    "hook": serve_cmd.run_hook,
+    "mcp": serve_cmd.run_mcp,
+    "inject": read_cmd.run_inject,
+    "install-hooks": hooks_cmd.run_install_hooks,
+    "flush": write_cmd.run_flush,
+    "graph": graph_cmd.run_graph,
+    "doctor": diag_cmd.run_doctor,
+    "status": diag_cmd.run_status,
+    "openclaw-setup": diag_cmd.run_openclaw_setup,
+    # Universal Agent Memory v7 — graph, cognitive, export, fork
+    "cognitive-sleep": cognitive_cmd.run_cognitive_sleep,
+    "audit": cognitive_cmd.run_audit,
+    "export-bundle": cognitive_cmd.run_export,
+    "import": cognitive_cmd.run_import,
+    "fork": cognitive_cmd.run_fork,
+    "graph-edge": cognitive_cmd.run_graph_edge,
+    "subgraph": cognitive_cmd.run_subgraph,
+    "graph-rebuild": cognitive_cmd.run_graph_rebuild,
+    "wiki-reclassify-legacy": cognitive_cmd.run_wiki_reclassify_legacy,
+}
+
+
+def main(argv: list | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in {"-h", "--help"}:
+        print(__doc__)
+        return 0
+    cmd, rest = args[0], args[1:]
+    fn = COMMANDS.get(cmd)
+    if fn is None:
+        print(f"unknown command: {cmd}", file=sys.stderr)
+        return 2
+    return fn(rest)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

loop_memory/engine/loop.py

@@ -0,0 +1,247 @@
+"""The Loop Engine.
+
+Each call to ``engine.turn(user_msg)`` runs the canonical four-stage loop:
+
+    1. RETRIEVE   — pull relevant items from long-term memory, recent
+                    episodes, and any open task plan.
+    2. GENERATE   — build an augmented prompt and ask the LLM to
+                    produce an answer.
+    3. REFLECT    — turn the new exchange into durable facts.
+    4. STORE      — persist facts, record an episode, push to short-term
+                    scratchpad with periodic compaction + GC.
+
+The engine is intentionally small and synchronous. It is the *contract*
+the rest of the project depends on. Replace the LLM, reflector, embedder,
+or vector store to specialize the loop without touching this file.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from ..backends.embedding import BaseEmbedder, IdentityEmbedder
+from ..backends.vector_store import InMemoryVectorStore, VectorStore
+from ..llm.base import ChatHistory, LLMClient, Message
+from ..memory.types import (
+    EpisodicMemory,
+    LongTermMemory,
+    MemoryItem,
+    ProceduralMemory,
+    ShortTermMemory,
+)
+from .reflect import Reflector, summarize_window
+
+log = logging.getLogger(__name__)
+
+
+SYSTEM_PROMPT = (
+    "You are a thoughtful assistant with persistent memory.\n"
+    "You will be given RELEVANT MEMORIES recalled from long-term storage, "
+    "a brief EPISODE LOG of recent events, and any open TASK PLANS. "
+    "Use them naturally when they help. If the user is mid-task, continue "
+    "the plan instead of starting a new one. Never claim to remember "
+    "something that isn't in the memory section."
+)
+
+
+@dataclass
+class LoopResult:
+    reply: str
+    retrieved: list[MemoryItem] = field(default_factory=list)
+    stored: list[MemoryItem] = field(default_factory=list)
+    reflection: list[MemoryItem] = field(default_factory=list)
+    diagnostics: dict = field(default_factory=dict)
+
+
+class LoopEngine:
+    def __init__(
+        self,
+        llm: LLMClient,
+        embedder: BaseEmbedder | None = None,
+        longterm: LongTermMemory | None = None,
+        episodic: EpisodicMemory | None = None,
+        procedural: ProceduralMemory | None = None,
+        vector_store: VectorStore | None = None,
+        short_capacity: int = 16,
+        compact_at: int | None = None,
+    ) -> None:
+        if llm is None:
+            raise ValueError("llm is required")
+        self.llm = llm
+        self.embedder = embedder or IdentityEmbedder()
+        self.short = ShortTermMemory(capacity=short_capacity)
+        self.long = longterm or LongTermMemory()
+        self.episodic = episodic or EpisodicMemory()
+        self.procedural = procedural or ProceduralMemory()
+        self.vector_store: VectorStore = vector_store or InMemoryVectorStore()
+        self.compact_at = compact_at if compact_at is not None else short_capacity
+        self.reflector: Callable[[str], list[MemoryItem]] = Reflector(
+            llm=self.llm, use_llm=False
+        ).extract
+
+    # --- public hooks ------------------------------------------------------
+
+    def set_reflector(self, fn: Callable[[str], list[MemoryItem]]) -> None:
+        """Replace the reflection step. ``fn`` receives raw user text."""
+        self.reflector = fn
+
+    def push_plan(self, goal_text: str) -> MemoryItem:
+        goal = MemoryItem(text=goal_text, importance=0.6, kind="plan", tags=["goal"])
+        self.procedural.push(goal)
+        return goal
+
+    def complete_current_plan(self) -> MemoryItem | None:
+        return self.procedural.complete_top()
+
+    def recall(self, query: str, k: int = 5) -> list[MemoryItem]:
+        q_emb = self.embedder.embed_query(query) if self.embedder.dim else None
+        return self.long.search(query_embedding=q_emb, top_k=k)
+
+    # --- the canonical loop ------------------------------------------------
+
+    def turn(
+        self,
+        user_msg: str,
+        *,
+        k: int = 5,
+        max_chars: int = 6000,
+    ) -> LoopResult:
+        if not isinstance(user_msg, str) or not user_msg.strip():
+            raise ValueError("user_msg must be a non-empty string")
+
+        # --- 1. RETRIEVE ---
+        q_emb = self.embedder.embed_query(user_msg) if self.embedder.dim else None
+        retrieved = self.long.search(query_embedding=q_emb, top_k=k)
+        recent_episodes = self.episodic.recent(3)
+        current_plan = self.procedural.current()
+
+        memory_block = self._format_memory_block(retrieved, recent_episodes, current_plan)
+        short_window = self.short.items()
+        short_text = "\n".join(f"- [{m.kind}] {m.text}" for m in short_window)
+
+        prompt = (
+            f"{memory_block}\n\n"
+            f"RECENT SCRATCHPAD:\n{short_text or '(empty)'}\n\n"
+            f"USER: {user_msg}\n"
+            f"ASSISTANT:"
+        )
+        # Hard cap so a runaway prompt never explodes the LLM context.
+        if len(prompt) > max_chars:
+            prompt = prompt[: max(0, max_chars - 1)].rstrip() + "…"
+
+        # --- 2. GENERATE ---
+        history = ChatHistory(
+            system=SYSTEM_PROMPT,
+            messages=[Message("user", prompt)],
+        )
+        t0 = time.time()
+        try:
+            reply = self.llm.complete(history)
+        except Exception:  # pragma: no cover — exercised only with bad adapters
+            log.exception("LLM call failed during turn()")
+            raise
+        gen_ms = (time.time() - t0) * 1000
+
+        # --- 3. REFLECT ---
+        try:
+            reflection = self.reflector(user_msg) or []
+        except Exception:
+            log.exception("Reflector failed; continuing without storing new facts")
+            reflection = []
+
+        if reflection and self.embedder.dim:
+            vecs = self.embedder.embed(reflection)
+            for item, vec in zip(reflection, vecs, strict=False):
+                item.embedding = vec
+        added_ltm = self.long.extend(reflection)
+        if reflection and self.embedder.dim:
+            try:
+                self.vector_store.add([it for it in added_ltm if it.embedding is not None])
+            except Exception:
+                log.exception("Vector store add failed; continuing with in-LTM list")
+
+        # Record an episode for the exchange.
+        episode = MemoryItem(
+            text=f"user: {user_msg}\nassistant: {reply}",
+            importance=0.4,
+            kind="episode",
+        )
+        self.episodic.record(episode)
+
+        # --- 4. STORE ---
+        self.short.push(MemoryItem(text=f"user: {user_msg}", importance=0.4, kind="turn"))
+        self.short.push(MemoryItem(text=f"assistant: {reply}", importance=0.4, kind="turn"))
+
+        # Periodic compaction: roll the scratchpad into a single summary item.
+        if len(self.short._items) >= self.compact_at:
+            summary = MemoryItem(
+                text=f"summary: {summarize_window(short_window)}",
+                importance=0.55,
+                kind="reflection",
+            )
+            if self.embedder.dim:
+                summary.embedding = self.embedder.embed_text(summary.text)
+            self.long.add(summary)
+            self.short.clear()
+
+        # Background GC: drop expired long-term items on every turn.
+        gc_removed = self.long.gc()
+
+        diagnostics = {
+            "retrieved": len(retrieved),
+            "stored": len(added_ltm),
+            "reflection_candidates": len(reflection),
+            "scratchpad_size": len(self.short._items),
+            "long_term_size": len(self.long),
+            "episodes": len(self.episodic._events),
+            "open_plans": len(self.procedural.goals),
+            "expired_dropped": gc_removed,
+            "gen_ms": round(gen_ms, 1),
+            "prompt_chars": min(len(prompt), max_chars),
+        }
+        return LoopResult(
+            reply=reply,
+            retrieved=retrieved,
+            stored=added_ltm,
+            reflection=added_ltm,
+            diagnostics=diagnostics,
+        )
+
+    # --- helpers ------------------------------------------------------------
+
+    def _format_memory_block(
+        self,
+        retrieved,
+        recent_episodes,
+        current_plan: MemoryItem | None,
+    ) -> str:
+        parts = ["RELEVANT MEMORIES:"]
+        retrieved_list = list(retrieved)
+        if retrieved_list:
+            for i, m in enumerate(retrieved_list, 1):
+                parts.append(f"  {i}. ({m.kind}, importance={m.importance:.2f}) {m.text}")
+        else:
+            parts.append("  (none)")
+
+        parts.append("\nEPISODE LOG (most recent first):")
+        eps = list(recent_episodes)
+        if eps:
+            for m in reversed(eps):
+                parts.append(f"  - {m.text}")
+        else:
+            parts.append("  (none)")
+
+        if current_plan is not None:
+            parts.append(f"\nOPEN TASK PLAN: {current_plan.text}")
+        return "\n".join(parts)
+
+    def __repr__(self) -> str:
+        return (
+            f"LoopEngine(llm={self.llm.model}, "
+            f"short={len(self.short._items)}/{self.short.capacity}, "
+            f"long={len(self.long)}, episodes={len(self.episodic._events)}, "
+            f"plans={len(self.procedural.goals)})"
+        )

loop_memory/engine/reflect.py

@@ -0,0 +1,89 @@
+"""Reflection and summarization passes.
+
+The reflection step is what turns a sequence of raw messages into
+structured long-term memories. In production it's an LLM call; here
+we use a deterministic heuristic extractor so the framework remains
+usable without an API key. Plug in a smarter pass via
+``engine.set_reflector(...)``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from ..llm.base import LLMClient
+from ..memory.types import MemoryItem
+
+_NAME_RE = re.compile(r"\b(?:my name is|i am|i'm|call me)\s+([A-Z][a-zA-Z'-]{1,30})")
+_LIKE_RE = re.compile(r"\b(?:i (?:really )?(?:like|love|enjoy|prefer))\s+([^.!?\n]+)", re.IGNORECASE)
+_DISLIKE_RE = re.compile(r"\b(?:i (?:really )?(?:dislike|hate|avoid))\s+([^.!?\n]+)", re.IGNORECASE)
+_FACT_HINT = ("my ", "i ", "we ", "always", "never", "remember", "important")
+
+
+def heuristic_extract(text: str) -> list[MemoryItem]:
+    """Cheap, deterministic fact extractor. Used when no LLM reflector is set."""
+    found: list[MemoryItem] = []
+    name = _NAME_RE.search(text)
+    if name:
+        found.append(MemoryItem(text=f"User's name is {name.group(1)}.", importance=0.95, kind="fact", tags=["identity"]))
+    for m in _LIKE_RE.finditer(text):
+        found.append(MemoryItem(text=f"User likes: {m.group(1).strip()}.", importance=0.7, kind="fact", tags=["preference"]))
+    for m in _DISLIKE_RE.finditer(text):
+        found.append(MemoryItem(text=f"User dislikes: {m.group(1).strip()}.", importance=0.7, kind="fact", tags=["preference"]))
+    if not found:
+        lower = text.lower()
+        if any(h in lower for h in _FACT_HINT) and len(text) < 240:
+            found.append(MemoryItem(text=text.strip(), importance=0.5, kind="fact"))
+    return found
+
+
+def summarize_window(messages: Iterable[MemoryItem], max_chars: int = 240) -> str:
+    """Compress a short-term window into a single roll-up line."""
+    pieces = [m.text for m in messages]
+    joined = " | ".join(pieces)
+    if len(joined) <= max_chars:
+        return joined
+    return joined[: max_chars - 1].rstrip() + "…"
+
+
+class Reflector:
+    """Pluggable reflection pass.
+
+    Default uses ``heuristic_extract``. Pass an LLM-backed reflector
+    for higher-quality, fewer-false-positive fact extraction:
+
+        def llm_reflect(text, llm):
+            prompt = f"Extract durable user facts from: {text}\nReturn JSON list."
+            return [MemoryItem(text=s, importance=0.8) for s in parse(llm.complete(...))]
+        engine.set_reflector(llm_reflect)
+    """
+
+    def __init__(self, llm: LLMClient | None = None, use_llm: bool = False) -> None:
+        self.llm = llm
+        self.use_llm = use_llm
+
+    def extract(self, text: str) -> list[MemoryItem]:
+        if self.use_llm and self.llm is not None:
+            return self._llm_extract(text)
+        return heuristic_extract(text)
+
+    def _llm_extract(self, text: str) -> list[MemoryItem]:
+        # Contract: the LLM is asked to return one fact per line, no commentary.
+        from ..llm.base import ChatHistory
+
+        history = ChatHistory(
+            system="Extract durable user facts. One per line. No numbering. No preamble.",
+            messages=[{"role": "user", "content": text}],  # type: ignore[list-item]
+        ) if False else ChatHistory(
+            system="Extract durable user facts. One per line. No numbering. No preamble.",
+            messages=[],
+        )
+        history.messages.append(__import__("loop_memory.llm.base", fromlist=["Message"]).Message("user", text))
+        out = self.llm.complete(history)
+        facts: list[MemoryItem] = []
+        for line in out.splitlines():
+            line = line.strip(" -•\t")
+            if 2 <= len(line) <= 200:
+                facts.append(MemoryItem(text=line, importance=0.75, kind="fact"))
+        return facts or heuristic_extract(text)

loop_memory/examples/demo.py

@@ -0,0 +1,39 @@
+"""Run a short multi-turn conversation through the loop engine.
+
+No API keys required — uses the bundled EchoLLM and a HashingEmbedder,
+so this example is fully self-contained.
+"""
+
+from __future__ import annotations
+
+from loop_memory import EchoLLM, HashingEmbedder, LoopEngine
+
+
+def main() -> None:
+    engine = LoopEngine(llm=EchoLLM(), embedder=HashingEmbedder(dim=128))
+
+    plan = engine.push_plan("Help Mia plan a weekend trip to Hangzhou.")
+    print(f"[plan] {plan.text}\n")
+
+    turns = [
+        "Hi, my name is Mia. I really love matcha and I dislike spicy food.",
+        "I'm travelling this weekend — somewhere quiet, ideally with tea and a lake.",
+        "I'll be coming back next week. Can you summarise what we decided?",
+    ]
+    for msg in turns:
+        result = engine.turn(msg)
+        print(f"you>  {msg}")
+        print(f"bot>  {result.reply}")
+        print(f"     diag={result.diagnostics}")
+        print()
+
+    print("[recall: 'tea']")
+    for item in engine.recall("tea"):
+        print(f"  - ({item.kind}) {item.text}")
+
+    print("\n[final state]")
+    print(engine)
+
+
+if __name__ == "__main__":
+    main()

loop_memory/export/__init__.py

@@ -0,0 +1,39 @@
+"""White-box export for the Universal Agent Memory contract.
+
+The article the user pointed us at proposes a local-first,
+Git-trackable, human-readable ``MEMORY.md`` as the storage format
+for the long-term layer. This package brings that idea to
+loop-memory without breaking the SQLite store — ``export_bundle``
+turns the live state into a directory of Markdown + JSON, and
+``import_bundle`` rehydrates it.
+
+The bundle layout (under the chosen ``out_dir``) is:
+
+    out_dir/
+        MEMORY.md            # top-level "what we know about you"
+        INDEX.md             # file map
+        pages/               # one .md per wiki page (slug-named)
+        memories.jsonl       # raw memories (one JSON per line)
+        graph.json           # entities + relations
+        meta.json            # schema version, export time, agent_id, user_id
+        sessions.json        # sessions index (titles + timestamps)
+
+Git-friendly by design: every file is small, text-only, and
+deterministically sorted so a diff shows exactly what the agent
+learned. Re-importing is idempotent (upsert by slug for pages,
+``(agent_id, user_id, external_id)`` for memories).
+"""
+
+from .memory_md import (
+    export_bundle,
+    import_bundle,
+    fork_snapshot,
+    write_memory_md,
+)
+
+__all__ = [
+    "export_bundle",
+    "import_bundle",
+    "fork_snapshot",
+    "write_memory_md",
+]