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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.3
+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
@@ -432,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). |
 
@@ -448,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

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

@@ -388,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). |
 
@@ -404,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

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.3 → 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.",
 }
 
 

{loop_memory-0.4.3 → loop_memory-0.4.4}/loop_memory/storage/sqlite_store.py

@@ -1280,6 +1280,13 @@ class MemoryStore:
                     "LIMIT ?"
                 )
                 rows = c.execute(sql, (*params, *tag_params, limit * 3)).fetchall()
+                # Short-query mode: when a query has only 1-2 tokens the
+                # lexical overlap is too narrow to rank by itself, so we
+                # also weight ``recall_count`` -- a memory the user has
+                # surfaced before is more likely to be the one they want
+                # this time too. Capped at +30 % so it nudges rather than
+                # dominates the importance + score multipliers.
+                short_query = len(tokens) <= 2
                 for r in rows:
                     tags = []
                     try:
@@ -1293,6 +1300,11 @@ class MemoryStore:
                     score = body_hits + 2 * tag_hits
                     score *= 0.5 + float(r["importance"] or 0) * 0.8
                     score *= 0.7 + float(r["score"] or 0) * 0.6
+                    if short_query:
+                        recall_count = int(r["recall_count"] or 0)
+                        # log1p saturates so a memory with thousands of
+                        # recalls does not crowd out everything else.
+                        score *= 1.0 + min(0.3, recall_count * 0.03)
                     out["memories"].append({
                         "id": r["id"],
                         "kind": "memory",

{loop_memory-0.4.3 → loop_memory-0.4.4}/loop_memory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.3
+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
@@ -432,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). |
 
@@ -448,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

{loop_memory-0.4.3 → loop_memory-0.4.4}/loop_memory.egg-info/SOURCES.txt

@@ -24,6 +24,7 @@ loop_memory/cli/commands/diag.py
 loop_memory/cli/commands/graph.py
 loop_memory/cli/commands/hooks.py
 loop_memory/cli/commands/read.py
+loop_memory/cli/commands/rules.py
 loop_memory/cli/commands/serve.py
 loop_memory/cli/commands/write.py
 loop_memory/engine/__init__.py
@@ -89,6 +90,7 @@ tests/test_admin_ingest_route.py
 tests/test_agent_memory_api.py
 tests/test_agent_memory_sdk.py
 tests/test_auth_token_rotate.py
+tests/test_cli_rules.py
 tests/test_cli_v7.py
 tests/test_cli_version.py
 tests/test_contradictions.py
@@ -114,6 +116,7 @@ tests/test_secrets.py
 tests/test_serve_app.py
 tests/test_serve_handlers.py
 tests/test_session_order.py
+tests/test_short_query.py
 tests/test_store.py
 tests/test_summarization.py
 tests/test_universal_memory.py

{loop_memory-0.4.3 → loop_memory-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loop-memory"
-version = "0.4.3"
+version = "0.4.4"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.10"

loop_memory-0.4.4/tests/test_cli_rules.py

@@ -0,0 +1,161 @@
+"""Tests for the rules installer (Audit 2026-08-23)."""
+import os
+import tempfile
+import unittest
+from pathlib import Path
+
+from loop_memory.cli.main import main, COMMAND_HELP
+from loop_memory.cli.commands.rules import (
+    AGENT_TARGETS,
+    MARKER,
+    _install,
+    _render_block,
+    _resolve_target,
+    run_rules,
+)
+
+
+class RulesInstallerTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = tempfile.TemporaryDirectory(prefix="loop_rules_")
+        self.root = Path(self.tmp.name)
+
+    def tearDown(self) -> None:
+        self.tmp.cleanup()
+
+    def test_renders_generic_block_with_marker(self) -> None:
+        block = _render_block("generic")
+        self.assertIn(MARKER, block)
+        self.assertIn("Memory discipline", block)
+        self.assertIn("task start", block)
+        self.assertIn("Mid-task", block)
+        self.assertIn("Wrap-up", block)
+
+    def test_renders_agent_specific_block(self) -> None:
+        for agent in ("codex", "claude", "hermes", "openclaw"):
+            block = _render_block(agent)
+            self.assertIn(MARKER, block, agent)
+
+    def test_hermes_block_has_hermes_section(self) -> None:
+        block = _render_block("hermes")
+        self.assertIn("Hermes-specific", block)
+
+    def test_openclaw_block_has_openclaw_section(self) -> None:
+        block = _render_block("openclaw")
+        self.assertIn("OpenClaw-specific", block)
+
+    def test_resolve_target_known_agents(self) -> None:
+        self.assertEqual(_resolve_target("codex", self.root), self.root / "AGENTS.md")
+        self.assertEqual(_resolve_target("claude", self.root), self.root / "CLAUDE.md")
+        self.assertEqual(_resolve_target("hermes", self.root), self.root / "AGENTS.md")
+        self.assertEqual(_resolve_target("openclaw", self.root), self.root / "AGENTS.md")
+
+    def test_resolve_target_unknown_falls_back_to_agents_md(self) -> None:
+        self.assertEqual(_resolve_target("claude-cli", self.root),
+                         self.root / "AGENTS.md")
+        self.assertEqual(_resolve_target("anything", self.root),
+                         self.root / "AGENTS.md")
+
+    def test_install_creates_new_file(self) -> None:
+        status, target = _install(self.root, "codex", force=False)
+        self.assertEqual(status, "installed")
+        # Then via run_rules we should actually write.
+        self.assertEqual(run_rules(["--agent", "codex", "--write", "--cwd",
+                                     str(self.root)]), 0)
+        target = self.root / "AGENTS.md"
+        self.assertTrue(target.exists())
+        content = target.read_text(encoding="utf-8")
+        self.assertIn(MARKER, content)
+        self.assertIn("Memory discipline", content)
+
+    def test_install_appends_without_overwriting_user_content(self) -> None:
+        target = self.root / "AGENTS.md"
+        target.write_text(
+            "# User's own rule\n\nDo not touch this.\n",
+            encoding="utf-8",
+        )
+        self.assertEqual(run_rules(["--agent", "codex", "--write",
+                                     "--cwd", str(self.root)]), 0)
+        content = target.read_text(encoding="utf-8")
+        self.assertIn("Do not touch this.", content)
+        self.assertIn(MARKER, content)
+        # User content must appear before our appended block.
+        self.assertLess(content.index("Do not touch this."),
+                        content.index(MARKER))
+
+    def test_install_is_idempotent(self) -> None:
+        self.assertEqual(run_rules(["--agent", "codex", "--write",
+                                     "--cwd", str(self.root)]), 0)
+        first = (self.root / "AGENTS.md").read_text(encoding="utf-8")
+        # Second run: same content, no duplicate block.
+        self.assertEqual(run_rules(["--agent", "codex", "--write",
+                                     "--cwd", str(self.root)]), 0)
+        second = (self.root / "AGENTS.md").read_text(encoding="utf-8")
+        self.assertEqual(first, second)
+        # The block contains the marker twice (open + close comment).
+        # Re-running is a no-op so the count must stay at 2.
+        self.assertEqual(first.count(MARKER), 2)
+        self.assertEqual(second.count(MARKER), 2)
+        self.assertEqual(first, second)
+
+    def test_force_overwrites_marker_span(self) -> None:
+        # Seed a user rule above the discipline block.
+        (self.root / "AGENTS.md").write_text(
+            "# user-rule\n\nkeep me\n",
+            encoding="utf-8",
+        )
+        self.assertEqual(run_rules(["--agent", "codex", "--write",
+                                     "--cwd", str(self.root)]), 0)
+        first = (self.root / "AGENTS.md").read_text(encoding="utf-8")
+        # --force refreshes the discipline block in place; user content
+        # above the start marker must stay byte-identical.
+        self.assertEqual(run_rules(["--agent", "codex", "--write",
+                                     "--force", "--cwd", str(self.root)]), 0)
+        second = (self.root / "AGENTS.md").read_text(encoding="utf-8")
+        # User content is preserved.
+        self.assertIn("keep me", second)
+        # Marker count stays at 2 (one open + one close).
+        self.assertEqual(first.count(MARKER), 2)
+        self.assertEqual(second.count(MARKER), 2)
+
+    def test_claude_targets_claudemd(self) -> None:
+        self.assertEqual(run_rules(["--agent", "claude", "--write",
+                                     "--cwd", str(self.root)]), 0)
+        target = self.root / "CLAUDE.md"
+        self.assertTrue(target.exists())
+        self.assertNotEqual(target, self.root / "AGENTS.md")
+        self.assertIn(MARKER, target.read_text(encoding="utf-8"))
+
+    def test_print_mode_prints_to_stdout_no_write(self) -> None:
+        import io
+        from unittest import mock
+        buf = io.StringIO()
+        with mock.patch("sys.stdout", buf):
+            self.assertEqual(run_rules(["--agent", "generic"]), 0)
+        out = buf.getvalue()
+        self.assertIn(MARKER, out)
+        # Print mode must NOT create any file.
+        self.assertEqual(list(self.root.iterdir()), [])
+
+    def test_command_help_is_present(self) -> None:
+        self.assertIn("rules", COMMAND_HELP)
+        self.assertIn("--write", COMMAND_HELP["rules"])
+        self.assertIn("--agent", COMMAND_HELP["rules"])
+
+    def test_help_via_dispatcher_exits_zero(self) -> None:
+        # Same pattern as ``test_cli_v7`` — exercises the dispatcher
+        # path for the new subcommand.
+        self.assertEqual(main(["rules", "--help"]), 0)
+
+    def test_unknown_argument_returns_2(self) -> None:
+        self.assertEqual(run_rules(["--bogus"]), 2)
+
+    def test_agent_targets_map_matches_shipped_agents(self) -> None:
+        # The shipped-agents mapping must cover everything the README
+        # advertises (4 + generic).
+        for agent in ("codex", "claude", "hermes", "openclaw", "generic"):
+            self.assertIn(agent, AGENT_TARGETS)
+
+
+if __name__ == "__main__":
+    unittest.main()

loop_memory-0.4.4/tests/test_short_query.py

@@ -0,0 +1,143 @@
+"""Tests for the recall() short-query tightening (Audit 2026-08-23)."""
+import tempfile
+import unittest
+from pathlib import Path
+
+from loop_memory.storage.sqlite_store import MemoryStore
+
+
+def _new_store() -> MemoryStore:
+    tmp = Path(tempfile.mkdtemp(prefix="loop_shortq_"))
+    return MemoryStore(tmp / "short.db")
+
+
+class RecallShortQueryTests(unittest.TestCase):
+    """Audit 2026-08-23: Cognee v1.5.2 short-query ranking.
+
+    When a query has 1-2 tokens, ``recall()`` boosts
+    ``recall_count`` so a memory the user has already surfaced wins
+    over a memory that only matches the substring but was never
+    actually useful. These tests pin both the boost and the cap so a
+    regression toward silent-noise OR toward runaway crowd-out both
+    fail CI.
+    """
+
+    def setUp(self) -> None:
+        self.store = _new_store()
+
+    def _seed(self):
+        # Two memories that match the same short query. The recalled
+        # one (b1) should outrank the never-recalled one (b2) once
+        # recall() sees the short-query boost.
+        a1 = self.store.upsert_memory(
+            kind="fact", text="database is postgres",
+            importance=0.5, agent_id="bot", user_id="u1",
+        )
+        a2 = self.store.upsert_memory(
+            kind="fact", text="uses postgres for orders",
+            importance=0.5, agent_id="bot", user_id="u1",
+        )
+        # Bump the second one several times so recall_count > 0.
+        for _ in range(5):
+            self.store.bump_recalls([a2.id])
+        return a1.id, a2.id
+
+    def test_short_query_recall_boost_prefers_recalled_memory(self) -> None:
+        _never, recalled = self._seed()
+        r = self.store.recall("postgres")
+        # Top hit is the recalled memory, not the never-recalled one.
+        ids = [m["id"] for m in r["memories"]]
+        self.assertIn(recalled, ids)
+        self.assertEqual(ids[0], recalled)
+
+    def test_short_query_boost_is_capped(self) -> None:
+        """A runaway recall_count must not crowd out everything else."""
+        # Seed a memory with 1000 recalls vs a sibling with 0.
+        a_lo = self.store.upsert_memory(
+            kind="fact", text="database is postgres",
+            importance=0.5, agent_id="bot",
+        )
+        a_hi = self.store.upsert_memory(
+            kind="fact", text="database is postgres too",
+            importance=0.5, agent_id="bot",
+        )
+        for _ in range(1000):
+            self.store.bump_recalls([a_hi.id])
+        r = self.store.recall("postgres")
+        scores = {m["id"]: m["score"] for m in r["memories"]}
+        # The cap is +30% so the high-recall memory wins, but the
+        # low-recall sibling must NOT be zeroed-out.
+        if a_hi.id in scores and a_lo.id in scores:
+            self.assertGreater(scores[a_hi.id], scores[a_lo.id])
+            # Ratio is bounded by 1.0 + cap = 1.30 (modulo rounding).
+            ratio = scores[a_hi.id] / max(scores[a_lo.id], 0.001)
+            self.assertLess(ratio, 1.5, f"boost overrun: {ratio:.3f}")
+
+    def test_short_query_boost_disabled_for_long_query(self) -> None:
+        """3+ tokens must NOT apply the recall_count boost.
+
+        Long queries have enough lexical overlap to rank by hits, so
+        adding recall_count on top would over-weight popular
+        memories and hide fresh-but-relevant ones.
+        """
+        # Seed two memories; only one has been recalled.
+        a_fresh = self.store.upsert_memory(
+            kind="fact",
+            text="Postgres orders table is used by service",
+            importance=0.5, agent_id="bot",
+        )
+        a_pop = self.store.upsert_memory(
+            kind="fact",
+            text="Postgres cache table is used by service",
+            importance=0.5, agent_id="bot",
+        )
+        for _ in range(10):
+            self.store.bump_recalls([a_pop.id])
+        # Three tokens -> NOT short.
+        r = self.store.recall("Postgres orders table")
+        # Both should be returned; ordering is by lexical signal
+        # (body_hits + importance + score), not by recall_count.
+        ids = [m["id"] for m in r["memories"]]
+        self.assertIn(a_fresh.id, ids)
+        self.assertIn(a_pop.id, ids)
+
+    def test_short_query_two_token_boundary(self) -> None:
+        """Two tokens IS short (len(tokens) <= 2)."""
+        store = _new_store()
+        _ = store.upsert_memory(
+            kind="fact", text="team uses postgres",
+            importance=0.5, agent_id="bot",
+        )
+        a2 = store.upsert_memory(
+            kind="fact", text="team uses postgres for orders",
+            importance=0.5, agent_id="bot",
+        )
+        for _ in range(5):
+            store.bump_recalls([a2.id])
+        r = store.recall("team postgres")
+        ids = [m["id"] for m in r["memories"]]
+        # 2 tokens -> short mode -> recalled memory wins.
+        self.assertEqual(ids[0], a2.id)
+
+    def test_short_query_zero_recall_count_no_change(self) -> None:
+        """Zero recall_count must NOT change the score (no boost, no penalty)."""
+        store = _new_store()
+        store.upsert_memory(
+            kind="fact", text="team uses postgres",
+            importance=0.5, agent_id="bot",
+        )
+        store.upsert_memory(
+            kind="fact", text="team uses postgres for orders",
+            importance=0.5, agent_id="bot",
+        )
+        r = store.recall("team postgres")
+        # Without bumps, both have recall_count=0; the boost should
+        # not flip the ranking purely on that field.
+        ids = [m["id"] for m in r["memories"]]
+        # The two-token query returns both; either order is fine since
+        # recall_count=0 means the multiplier is 1.0 for both.
+        self.assertEqual(len(ids), 2)
+
+
+if __name__ == "__main__":
+    unittest.main()