loop-memory 0.4.2__tar.gz → 0.4.4__tar.gz

{loop_memory-0.4.2 → loop_memory-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.2
+Version: 0.4.4
 Summary: A general-purpose, local memory system for every AI agent you run. Loop Memory auto-captures conversations from Codex / Claude / Hermes / OpenClaw, scores them by importance × recency × usage × feedback, distils them into a curated wiki, and serves everything from a single web UI.
 Author: Loop Memory contributors <loop-memory@users.noreply.github.com>
 License-Expression: MIT
@@ -402,6 +402,15 @@ pass** over the store:
 
 Dry-run by default; pass `--apply` to commit.
 
+**Observability (since 0.4.3).** The report carries per-stage
+timings (``scan``, ``stale``, ``merge``, ``contradict``, ``apply``,
+``audit``) and an explicit ``aborted`` flag with an ``abort_reason``
+that names the stage the budget fired in. Pass
+``--deadline-seconds <N>`` (HTTP: ``POST /api/v1/cognitive/sleep``
+with ``{"deadline_seconds": N}``; SDK: ``client.cognitive_sleep(deadline_seconds=N)``)
+to bound the sweep — useful for nightly cron, where a stuck
+sweep should leave a loud trace instead of a silent spinner.
+
 ### Knowledge graph
 
 `loop-memory graph-rebuild` extracts entities from every distilled
@@ -423,6 +432,7 @@ automatically:
 | Command                          | What it does                                                                 |
 | -------------------------------- | ---------------------------------------------------------------------------- |
 | `loop-memory install-hooks`      | Auto-detect `~/.codex`, `~/.claude`, `~/.hermes` and write MCP + SessionStart hook configs in place. Idempotent — re-run any time. |
+| `loop-memory rules --write`       | Append the three-phase memory-discipline block (task start / mid-task / wrap-up) into the agent's rule file (`AGENTS.md` for codex / hermes / openclaw, `CLAUDE.md` for claude). **Never overwrites user content.** |
 | `loop-memory inject [query]`     | Print a `# Long-term memory context` markdown block (distilled wiki + recent relevant memories) for a SessionStart hook. |
 | `loop-memory mcp`                | Run the **stdio MCP server** with memory, graph, and cognitive tools (`recall`, `remember`, `forget`, `feedback`, `remember_edge`, `subgraph`, `cognitive_sleep`, `audit`, and wiki tools). |
 
@@ -439,6 +449,11 @@ loop-memory install-hooks       # writes ~/.codex/config.toml + ~/.claude/{mcp.j
 Manual smoke-test without restarting the client:
 
 ```bash
+# one-shot: install the memory-discipline block into the agent's
+# rule file so the client calls `recall` on every task start.
+loop-memory rules --agent codex --write   # writes ./AGENTS.md (append, never overwrite)
+loop-memory rules --agent claude --write  # writes ./CLAUDE.md
+
 loop-memory inject                       # dumps the warm-start block to stdout
 printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"wiki_summary"}}\n' \
   | loop-memory mcp                      # round-trips JSON-RPC over stdio
@@ -632,6 +647,24 @@ classifier is local and makes no model or network request on a wiki write.
 
 ---
 
+### LLM env-var overrides
+
+The OpenAI-compat / Anthropic / Ollama providers (and the optional
+``openai`` adapter) honour two env-var knobs so you can pin
+distillation deterministically without touching the behaviour
+config:
+
+- ``LLM_TEMPERATURE`` — float, defaults to ``0.3`` (or the explicit
+  ``kwargs.temperature``). Invalid values are ignored with a warning.
+- ``LLM_SEED`` — int, sent as ``seed`` for OpenAI / Anthropic /
+  Ollama where supported. Omitting it preserves the existing
+  "no seed" behaviour so older call sites do not need to migrate.
+
+Both env vars are read at every ``complete()`` call, so a single
+``export LLM_SEED=42`` plus a nightly cron makes wiki distillation
+reproducible. Pinned by 11 cases in
+``tests/test_llm_providers.py::LLMEnvVarTests``.
+
 ## FAQ & troubleshooting
 
 **Q: `pip install loop-memory` succeeds but `loop-memory serve` says `ModuleNotFoundError: No module named 'fastapi'`.**

{loop_memory-0.4.2 → loop_memory-0.4.4}/README.md

@@ -358,6 +358,15 @@ pass** over the store:
 
 Dry-run by default; pass `--apply` to commit.
 
+**Observability (since 0.4.3).** The report carries per-stage
+timings (``scan``, ``stale``, ``merge``, ``contradict``, ``apply``,
+``audit``) and an explicit ``aborted`` flag with an ``abort_reason``
+that names the stage the budget fired in. Pass
+``--deadline-seconds <N>`` (HTTP: ``POST /api/v1/cognitive/sleep``
+with ``{"deadline_seconds": N}``; SDK: ``client.cognitive_sleep(deadline_seconds=N)``)
+to bound the sweep — useful for nightly cron, where a stuck
+sweep should leave a loud trace instead of a silent spinner.
+
 ### Knowledge graph
 
 `loop-memory graph-rebuild` extracts entities from every distilled
@@ -379,6 +388,7 @@ automatically:
 | Command                          | What it does                                                                 |
 | -------------------------------- | ---------------------------------------------------------------------------- |
 | `loop-memory install-hooks`      | Auto-detect `~/.codex`, `~/.claude`, `~/.hermes` and write MCP + SessionStart hook configs in place. Idempotent — re-run any time. |
+| `loop-memory rules --write`       | Append the three-phase memory-discipline block (task start / mid-task / wrap-up) into the agent's rule file (`AGENTS.md` for codex / hermes / openclaw, `CLAUDE.md` for claude). **Never overwrites user content.** |
 | `loop-memory inject [query]`     | Print a `# Long-term memory context` markdown block (distilled wiki + recent relevant memories) for a SessionStart hook. |
 | `loop-memory mcp`                | Run the **stdio MCP server** with memory, graph, and cognitive tools (`recall`, `remember`, `forget`, `feedback`, `remember_edge`, `subgraph`, `cognitive_sleep`, `audit`, and wiki tools). |
 
@@ -395,6 +405,11 @@ loop-memory install-hooks       # writes ~/.codex/config.toml + ~/.claude/{mcp.j
 Manual smoke-test without restarting the client:
 
 ```bash
+# one-shot: install the memory-discipline block into the agent's
+# rule file so the client calls `recall` on every task start.
+loop-memory rules --agent codex --write   # writes ./AGENTS.md (append, never overwrite)
+loop-memory rules --agent claude --write  # writes ./CLAUDE.md
+
 loop-memory inject                       # dumps the warm-start block to stdout
 printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"wiki_summary"}}\n' \
   | loop-memory mcp                      # round-trips JSON-RPC over stdio
@@ -588,6 +603,24 @@ classifier is local and makes no model or network request on a wiki write.
 
 ---
 
+### LLM env-var overrides
+
+The OpenAI-compat / Anthropic / Ollama providers (and the optional
+``openai`` adapter) honour two env-var knobs so you can pin
+distillation deterministically without touching the behaviour
+config:
+
+- ``LLM_TEMPERATURE`` — float, defaults to ``0.3`` (or the explicit
+  ``kwargs.temperature``). Invalid values are ignored with a warning.
+- ``LLM_SEED`` — int, sent as ``seed`` for OpenAI / Anthropic /
+  Ollama where supported. Omitting it preserves the existing
+  "no seed" behaviour so older call sites do not need to migrate.
+
+Both env vars are read at every ``complete()`` call, so a single
+``export LLM_SEED=42`` plus a nightly cron makes wiki distillation
+reproducible. Pinned by 11 cases in
+``tests/test_llm_providers.py::LLMEnvVarTests``.
+
 ## FAQ & troubleshooting
 
 **Q: `pip install loop-memory` succeeds but `loop-memory serve` says `ModuleNotFoundError: No module named 'fastapi'`.**

loop_memory-0.4.4/loop_memory/cli/commands/rules.py

@@ -0,0 +1,245 @@
+"""rules: install a memory-discipline block into the agent's rule file.
+
+Audit 2026-08-23: pattern adopted from
+``2672243194/agentbrain`` v0.4.3 (``agentbrain rules --agent … --write``,
+which appends a three-phase workflow block into CLAUDE.md /
+AGENTS.md / Cursor / Trae rule files). Loop Memory's port wires
+the same discipline into the four shipped agent targets:
+
+* ``codex``    -> ``AGENTS.md``   (Codex CLI convention)
+* ``claude``   -> ``CLAUDE.md``   (Claude Code convention)
+* ``hermes``   -> ``AGENTS.md``   (Hermes CLI also reads AGENTS.md)
+* ``openclaw`` -> ``AGENTS.md``   (OpenClaw reads AGENTS.md)
+* ``generic``  -> ``AGENTS.md``   (any other AGENTS.md-aware client)
+
+Safety properties:
+
+* Existing rule files are **never overwritten** — the block is
+  appended after the user's content. Their rules stay byte-identical.
+* **Idempotent** — a marker comment detects a prior install and
+  skips the write.
+* The CLI exits 0 even when the target file does not exist (it
+  creates an empty one) and when no ``--agent`` is given (it just
+  prints the generic block to stdout).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+# Marker line used to detect a prior install. The leading space +
+# trailing space keep the marker from accidentally colliding with a
+# user's prose like "loop-memory is great". Keep this string in sync
+# with the appended block below.
+MARKER = "<!-- loop-memory:rules:installed -->"
+
+# Agent-name -> relative path under cwd. Unknown agents fall back
+# to ``generic`` (AGENTS.md).
+AGENT_TARGETS: dict[str, str] = {
+    "codex":    "AGENTS.md",
+    "claude":   "CLAUDE.md",
+    "hermes":   "AGENTS.md",
+    "openclaw": "AGENTS.md",
+    "generic":  "AGENTS.md",
+}
+
+
+def _generic_block() -> str:
+    """The discipline block written to every agent's rule file."""
+    return (
+        f"\n{MARKER}\n"
+        "# Memory discipline (auto-installed by `loop-memory rules`).\n"
+        "# Re-run the same command to refresh in place; manual edits\n"
+        "# between the marker lines will be preserved on the next refresh.\n"
+        "\n"
+        "## At task start\n"
+        "\n"
+        "Before you read or write anything in this project, query Loop\n"
+        "Memory first so you can act on prior work instead of rebuilding\n"
+        "it. Use the project's existing memory tooling — for example\n"
+        "`loop-memory recall \"<task topic>\"` (shell), the `recall` MCP\n"
+        "tool, or the `inject` SessionStart hook if one is wired up.\n"
+        "Read the top hits before you start typing.\n"
+        "\n"
+        "## Mid-task\n"
+        "\n"
+        "Re-query whenever you switch subtask, hit an unexpected error,\n"
+        "or follow up a topic the initial query did not cover. Plain\n"
+        "continuation of the same line of thought does not need a\n"
+        "re-query — that is what saves tokens.\n"
+        "\n"
+        "## Wrap-up\n"
+        "\n"
+        "Each distinct reusable lesson — a non-obvious gotcha, a\n"
+        "convention you wish you'd known, a fix to a bug class —\n"
+        "should be written back via `loop-memory ingest` / the `add`\n"
+        "MCP tool, with user confirmation so nothing private lands in\n"
+        "the vault. Never paste secrets, tokens, or local paths into\n"
+        "a memory; use `${ENV:VAR_NAME}` placeholders or omit them.\n"
+        f"\n{MARKER} (end)\n"
+    )
+
+
+def _render_block(agent: str) -> str:
+    """Return the discipline block tailored to ``agent``."""
+    base = _generic_block()
+    if agent in {"claude", "codex"}:
+        return base
+    # Hermes / OpenClaw: same text but the explicit tool name in the
+    # hook line differs because the MCP tool prefix varies. The block
+    # already names the tool generically; we add one agent-specific
+    # clarifying line at the bottom for these two.
+    if agent == "hermes":
+        extra = (
+            "\n## Hermes-specific\n"
+            "\n"
+            "Hermes exposes Loop Memory through MCP too. The same\n"
+            "`recall` / `add` tool names apply; if you do not see\n"
+            "them in the MCP tool list, run\n"
+            "`loop-memory install-hooks` once and restart Hermes.\n"
+        )
+        return base.replace(f"\n{MARKER} (end)\n", extra + f"\n{MARKER} (end)\n")
+    if agent == "openclaw":
+        extra = (
+            "\n## OpenClaw-specific\n"
+            "\n"
+            "OpenClaw sessions are auto-ingested when\n"
+            "`loop-memory hook --source openclaw --watch <sessions-dir>`\n"
+            "is running. If the recall hits are empty, check that\n"
+            "the watcher is alive (`loop-memory doctor`) and that\n"
+            "the workspace log directory exists.\n"
+        )
+        return base.replace(f"\n{MARKER} (end)\n", extra + f"\n{MARKER} (end)\n")
+    return base
+
+
+def _resolve_target(agent: str, cwd: Path) -> Path:
+    """Map an agent name to its rule-file path under ``cwd``."""
+    rel = AGENT_TARGETS.get(agent)
+    if rel is None:
+        # Unknown agent — keep the same path as ``generic`` so the
+        # user still gets a working AGENTS.md and can rename it.
+        rel = AGENT_TARGETS["generic"]
+    return cwd / rel
+
+
+def _install(cwd: Path, agent: str, *, force: bool) -> tuple[str, str]:
+    """Install the block; return (status, message).
+
+    ``status`` is one of: ``installed``, ``already-installed``,
+    ``appended``, ``dry-run``.
+    """
+    target = _resolve_target(agent, cwd)
+    existing = ""
+    if target.exists():
+        try:
+            existing = target.read_text(encoding="utf-8")
+        except Exception as e:
+            return "error", f"could not read {target}: {e}"
+    if MARKER in existing and not force:
+        return "already-installed", str(target)
+    # ``run_rules`` does the actual write; this helper just classifies
+    # the request so callers can unit-test the marker-detection path.
+    return "installed", str(target)
+
+
+def run_rules(args: list) -> int:
+    """``loop-memory rules [--agent NAME] [--write] [--force] [--cwd PATH]``.
+
+    Behaviour:
+    * no args                     -> print the generic block to stdout
+    * ``--agent NAME``            -> print the agent-tailored block
+    * ``--write``                 -> install (append) into the agent's
+                                    rule file under cwd (or ``--cwd``)
+    * ``--force``                 -> overwrite a prior install in place
+                                    (still never touches user content
+                                    outside the marker lines)
+    """
+    agent = "generic"
+    write = False
+    force = False
+    cwd = Path.cwd()
+    it = iter(args)
+    for tok in it:
+        if tok == "--agent":
+            try:
+                agent = next(it)
+            except StopIteration:
+                print("--agent requires a name", file=sys.stderr)
+                return 2
+        elif tok == "--write":
+            write = True
+        elif tok == "--force":
+            force = True
+        elif tok == "--cwd":
+            try:
+                cwd = Path(next(it)).expanduser()
+            except StopIteration:
+                print("--cwd requires a path", file=sys.stderr)
+                return 2
+        elif tok in {"-h", "--help"}:
+            print(__doc__ or "loop-memory rules [--agent NAME] [--write] [--force]")
+            return 0
+        else:
+            print(f"unknown argument: {tok}", file=sys.stderr)
+            return 2
+
+    if not write:
+        sys.stdout.write(_render_block(agent))
+        return 0
+
+    target = _resolve_target(agent, cwd)
+    existing = ""
+    if target.exists():
+        try:
+            existing = target.read_text(encoding="utf-8")
+        except Exception as e:
+            print(f"could not read {target}: {e}", file=sys.stderr)
+            return 1
+
+    block = _render_block(agent)
+    if MARKER in existing and not force:
+        print(f"[loop-memory] rules: already installed in {target}")
+        return 0
+    if MARKER in existing and force:
+        # Replace the existing marker span in place: keep everything
+        # before the start marker and everything after the close
+        # marker, splice a fresh block between them. User content
+        # outside the marker lines is preserved byte-for-byte.
+        start_idx = existing.index(MARKER)
+        close_idx = existing.find(MARKER + " (end)", start_idx)
+        if close_idx < 0:
+            # Partial / corrupted install — fall back to append.
+            close_idx = len(existing)
+        else:
+            close_idx = existing.index("\n", close_idx)
+        new_content = existing[:start_idx].rstrip("\n") + "\n" + block + existing[close_idx:]
+        action = "refreshed"
+    else:
+        sep = ""
+        if existing and not existing.endswith("\n"):
+            sep = "\n"
+        new_content = existing + sep + block
+        action = "appended" if existing else "created"
+
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(new_content, encoding="utf-8")
+    except Exception as e:
+        print(f"[loop-memory] rules: write failed: {e}", file=sys.stderr)
+        return 1
+    print(f"[loop-memory] rules: {action} {target}")
+    return 0
+
+
+__all__ = [
+    "AGENT_TARGETS",
+    "MARKER",
+    "_generic_block",
+    "_install",
+    "_render_block",
+    "_resolve_target",
+    "run_rules",
+]

{loop_memory-0.4.2 → loop_memory-0.4.4}/loop_memory/cli/main.py

@@ -17,6 +17,8 @@ Usage:
     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 rules [--agent codex|claude|hermes|openclaw] [--write] [--force]
+                       # install the three-phase memory discipline block into the agent's rule file
     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
@@ -38,6 +40,7 @@ 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 rules as rules_cmd
 from .commands import serve as serve_cmd
 from .commands import write as write_cmd
 
@@ -113,6 +116,7 @@ COMMANDS = {
     "subgraph": cognitive_cmd.run_subgraph,
     "graph-rebuild": cognitive_cmd.run_graph_rebuild,
     "wiki-reclassify-legacy": cognitive_cmd.run_wiki_reclassify_legacy,
+    "rules": rules_cmd.run_rules,
     "version": _run_version,
 }
 
@@ -152,6 +156,7 @@ COMMAND_HELP: dict[str, str] = {
     "subgraph":               "loop-memory subgraph <query>   # print a small subgraph.",
     "version":                "loop-memory version   # print the installed distribution version.",
     "wiki-reclassify-legacy": "loop-memory wiki-reclassify-legacy   # back-fill scope + scope_filter for H4+H5 pages.",
+    "rules":                 "loop-memory rules [--agent codex|claude|hermes|openclaw] [--write] [--force]\n  Print, or append into the agent's rule file, the three-phase memory discipline (task start / mid-task / wrap-up). Never overwrites user content.",
 }