loop-memory 0.4.8__tar.gz → 0.4.10__tar.gz

{loop_memory-0.4.8 → loop_memory-0.4.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.8
+Version: 0.4.10
 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
@@ -66,6 +66,23 @@ Dynamic: license-file
 
 ---
 
+> **What's new in 0.4.10** — **path-safety guard** for the
+five export / snapshot endpoints. ``MemoryStore`` already
+validated query / wiki content; the new
+``_safe_resolve_path`` helper (audit 2026-09-23) closes the
+remaining path-traversal vector by refusing any path that
+points at the live SQLite store, a system directory
+(``/etc`` / ``/usr`` / ``/System``), or a sensitive dotfile
+(``~/.ssh`` / ``~/.aws`` / ``~/.gnupg``). Also in this
+release: a hard cap on the in-process LLM response cache
+(was unbounded; now 256 entries with FIFO eviction) and a
+fix for ``subgraph_for(max_hops=...)`` which used to ignore
+the argument and always walk one hop (now BFS up to N hops,
+hard-capped at 8). 29 new regression cases. [Full
+CHANGELOG →](./CHANGELOG.md#0410---2026-09-23)
+
+> **What's new in 0.4.9** — **OKF v0.2 export** + **bi-temporal `as_of` recall**. `loop-memory export-okf <dir>` writes an [Open Knowledge Format](https://github.com/okf/SPEC) v0.2 bundle — one `.md` file per wiki page with YAML frontmatter + an `index.md` index — so a Loop Memory store can be handed to any OKF-aware tool (Grep, Obsidian, akitaonrails/ai-memory, okf-agent-memory, ...) without re-parsing the body (audit 2026-09-20, Google OKF v0.2 spec + akitaonrails/ai-memory 2.0 + okf-memory/okf-agent-memory, all Apache-2.0/MIT, 2026-09-01 → 2026-09-06). `loop-memory recall <q> --as-of <ISO|epoch>` answers the bi-temporal question "what did we know about this query at that moment?" — a memory written after the moment is invisible, and a superseded memory walks its chain to find whether the invalidation had happened by then (audit 2026-09-20, loomcycle v1.33-v1.49 RFCs BL/BS/BU/BV/BW, Apache-2.0). Both shapes ship with HTTP routes (`POST /api/export/okf`, `GET /api/recall?as_of=...`). 34 new regression cases pin both shapes. [Full CHANGELOG →](./CHANGELOG.md#049---2026-09-20)
+
 > **What's new in 0.4.8** — **L0 outline recall** +
 > **per-agent identity bootstrap**. `loop-memory recall-paths <q>`
 > (and the new `recall --outline` flag) returns only `id` +

{loop_memory-0.4.8 → loop_memory-0.4.10}/README.md

@@ -22,6 +22,23 @@
 
 ---
 
+> **What's new in 0.4.10** — **path-safety guard** for the
+five export / snapshot endpoints. ``MemoryStore`` already
+validated query / wiki content; the new
+``_safe_resolve_path`` helper (audit 2026-09-23) closes the
+remaining path-traversal vector by refusing any path that
+points at the live SQLite store, a system directory
+(``/etc`` / ``/usr`` / ``/System``), or a sensitive dotfile
+(``~/.ssh`` / ``~/.aws`` / ``~/.gnupg``). Also in this
+release: a hard cap on the in-process LLM response cache
+(was unbounded; now 256 entries with FIFO eviction) and a
+fix for ``subgraph_for(max_hops=...)`` which used to ignore
+the argument and always walk one hop (now BFS up to N hops,
+hard-capped at 8). 29 new regression cases. [Full
+CHANGELOG →](./CHANGELOG.md#0410---2026-09-23)
+
+> **What's new in 0.4.9** — **OKF v0.2 export** + **bi-temporal `as_of` recall**. `loop-memory export-okf <dir>` writes an [Open Knowledge Format](https://github.com/okf/SPEC) v0.2 bundle — one `.md` file per wiki page with YAML frontmatter + an `index.md` index — so a Loop Memory store can be handed to any OKF-aware tool (Grep, Obsidian, akitaonrails/ai-memory, okf-agent-memory, ...) without re-parsing the body (audit 2026-09-20, Google OKF v0.2 spec + akitaonrails/ai-memory 2.0 + okf-memory/okf-agent-memory, all Apache-2.0/MIT, 2026-09-01 → 2026-09-06). `loop-memory recall <q> --as-of <ISO|epoch>` answers the bi-temporal question "what did we know about this query at that moment?" — a memory written after the moment is invisible, and a superseded memory walks its chain to find whether the invalidation had happened by then (audit 2026-09-20, loomcycle v1.33-v1.49 RFCs BL/BS/BU/BV/BW, Apache-2.0). Both shapes ship with HTTP routes (`POST /api/export/okf`, `GET /api/recall?as_of=...`). 34 new regression cases pin both shapes. [Full CHANGELOG →](./CHANGELOG.md#049---2026-09-20)
+
 > **What's new in 0.4.8** — **L0 outline recall** +
 > **per-agent identity bootstrap**. `loop-memory recall-paths <q>`
 > (and the new `recall --outline` flag) returns only `id` +

{loop_memory-0.4.8 → loop_memory-0.4.10}/loop_memory/cli/commands/cognitive.py

@@ -108,6 +108,17 @@ def _build_parser() -> argparse.ArgumentParser:
     rs.add_argument("in_path",
                     help="Source .memory.sqlite file")
 
+    # Audit 2026-09-20: OKF v0.2 bundle export
+    # (akitaonrails/ai-memory 2.0 + okf-memory/okf-agent-memory +
+    # Google OKF v0.2 spec).
+    eo = sub.add_parser(
+        "export-okf",
+        help="Export wiki pages as an OKF v0.2 markdown bundle")
+    eo.add_argument("out_dir",
+                    help="Destination directory for the bundle")
+    eo.add_argument("--scope", default=None,
+                    help="Filter: 'global' or a single source token (e.g. codex)")
+
     return p
 
 
@@ -342,3 +353,25 @@ def run_restore(args: list) -> int:
         return _emit(_restore(s, ns.in_path))
     except (FileNotFoundError, ValueError) as e:
         return _emit({"error": str(e)})
+
+
+def run_export_okf(args) -> int:
+    """``loop-memory export-okf <out_dir> [--scope SCOPE]``
+
+    Audit 2026-09-20: OKF v0.2 bundle export
+    (akitaonrails/ai-memory 2.0 + okf-memory/okf-agent-memory +
+    Google OKF v0.2 spec). Returns a summary dict with the bundle
+    root + per-page list so the caller can confirm the bundle is
+    sane. ``--scope`` accepts ``global`` (only globally-scoped
+    pages) or a single source token (only pages whose scope list
+    contains the token); omit the flag to emit every page.
+    """
+    import argparse as _ap
+    p = _ap.ArgumentParser(prog="loop-memory export-okf")
+    p.add_argument("out_dir")
+    p.add_argument("--scope", default=None)
+    p.add_argument("--db", default=os.environ.get("LOOP_MEMORY_DB", DEFAULT_DB))
+    ns = p.parse_args(args)
+    s = MemoryStore(ns.db)
+    r = s.export_okf(ns.out_dir, scope_filter=ns.scope)
+    return _emit(r)

{loop_memory-0.4.8 → loop_memory-0.4.10}/loop_memory/cli/commands/read.py

@@ -51,13 +51,17 @@ def run_stats(_args) -> int:
 
 
 def run_recall(args) -> int:
-    """Run ``loop-memory recall <query> [--verbose] [--limit N]``.
+    """Run ``loop-memory recall <query> [--verbose] [--outline] [--as-of T] [--limit N]``.
 
     With ``--verbose`` each memory hit is annotated with the
     ``why: [...]`` provenance labels produced by ``MemoryStore.recall``
-    (audit 2026-08-30, agentmemory v1.2.0 pattern). The wiki and
-    entity sections are unchanged — only the raw-memory block grows
-    the new line.
+    (audit 2026-08-30, agentmemory v1.2.0 pattern). ``--outline``
+    switches to the L0 list (audit 2026-09-13, tigerless-labs/
+    agent-memory v0.3.0). ``--as-of <float-or-ISO>`` enables
+    bi-temporal recall (audit 2026-09-20, loomcycle v1.33+) so a
+    caller can ask "what did we know about this query at that
+    moment?". The wiki and entity sections are unchanged — only
+    the raw-memory block grows the new line.
     """
     from ...storage.sqlite_store import MemoryStore
     if not args:
@@ -68,6 +72,7 @@ def run_recall(args) -> int:
     verbose = False
     outline = False
     limit = 10
+    as_of: float | None = None
     qargs: list[str] = []
     i = 0
     while i < len(args):
@@ -81,6 +86,24 @@ def run_recall(args) -> int:
             # routes the call to ``recall_paths`` below.
             outline = True
             i += 1
+        elif a == "--as-of" and i + 1 < len(args):
+            # Audit 2026-09-20 (loomcycle v1.33+) — bi-temporal
+            # recall: "what did we know about this query at that
+            # moment?". Accepts float epoch OR ISO-8601 string.
+            raw = args[i + 1].strip()
+            try:
+                as_of = float(raw)
+            except ValueError:
+                try:
+                    from datetime import datetime
+                    as_of = datetime.fromisoformat(
+                        raw.replace("Z", "+00:00")
+                    ).timestamp()
+                except Exception:
+                    return die(
+                        f"--as-of must be float epoch or ISO-8601; got {raw!r}"
+                    )
+            i += 2
         elif a == "--limit" and i + 1 < len(args):
             try:
                 limit = int(args[i + 1])
@@ -93,10 +116,15 @@ def run_recall(args) -> int:
             qargs.append(a)
             i += 1
     if not qargs:
-        return die("usage: loop-memory recall <query> [--verbose] [--outline] [--limit N]")
+        return die("usage: loop-memory recall <query> [--verbose] [--outline] [--as-of <ISO|epoch>] [--limit N]")
     store = MemoryStore(default_db_path())
     query = " ".join(qargs)
-    if outline:
+    if as_of is not None:
+        try:
+            r = store.recall_as_of(query, as_of, limit=limit)
+        except ValueError as e:
+            return die(str(e))
+    elif outline:
         r = store.recall_paths(query, limit=limit)
     else:
         r = store.recall(query, limit=limit)

{loop_memory-0.4.8 → loop_memory-0.4.10}/loop_memory/cli/main.py

@@ -125,6 +125,9 @@ COMMANDS = {
     # Audit 2026-09-13 — L0 outline recall + per-agent identity bootstrap.
     "recall-paths": read_cmd.run_recall_paths,
     "init": hooks_cmd.run_init,
+    # Audit 2026-09-20 — OKF v0.2 export (akitaonrails/ai-memory 2.0
+    # + okf-agent-memory + Google OKF spec).
+    "export-okf": cognitive_cmd.run_export_okf,
     "rules": rules_cmd.run_rules,
     "version": _run_version,
 }
@@ -158,7 +161,7 @@ COMMAND_HELP: dict[str, str] = {
     "install-hooks":          "loop-memory install-hooks   # auto-write MCP + SessionStart hooks for known clients.",
     "mcp":                    "loop-memory mcp   # stdio MCP server (for codex/claude/hermes). Requires ``[serve]`` for HTTP transport.",
     "openclaw-setup":         "loop-memory openclaw-setup   # install the openclaw/clawx auto-ingest watcher (launchd on macOS).",
-    "recall":                 "loop-memory recall <text>   # show top memories.",
+    "recall":                 "loop-memory recall <text> [--as-of <ISO|epoch>]   # show top memories (--as-of = bi-temporal recall).",
     "rescore":                "loop-memory rescore [--half-life 30]   # recompute memory scores.",
     "serve":                  "loop-memory serve [--port 7767] [--no-browser]   # start the local web UI. Requires the ``[serve]`` extra (fastapi + uvicorn).",
     "stats":                  "loop-memory stats   # counters.",
@@ -168,6 +171,7 @@ COMMAND_HELP: dict[str, str] = {
     "wiki-reclassify-legacy": "loop-memory wiki-reclassify-legacy   # back-fill scope + scope_filter for H4+H5 pages.",
     "memory-stats":           "loop-memory memory-stats <id> [--prefix]   # per-memory lifetime stats (audit 2026-09-06, agentmemory v1.3.0).",
     "snapshot":               "loop-memory snapshot <out.memory.sqlite>   # write a portable SQLite snapshot (audit 2026-09-06, codexa-memory v0.2.0).",
+    "export-okf":             "loop-memory export-okf <out_dir> [--scope S]   # write an OKF v0.2 bundle (audit 2026-09-20).",
     "restore":                "loop-memory restore <in.memory.sqlite>   # re-hydrate a portable SQLite snapshot.",
     # Audit 2026-09-13 — L0 outline recall (tigerless-labs/agent-memory v0.3.0).
     "recall-paths":           "loop-memory recall-paths <query> [--limit N]   # cheap L0 outline (id+abstract+score) instead of full text (audit 2026-09-13).",

{loop_memory-0.4.8 → loop_memory-0.4.10}/loop_memory/jobs/evolution.py

@@ -684,6 +684,11 @@ class EvolutionConsolidator:
         self._cache: dict[str, str] = {}
         self._cache_ttl = 300.0
         self._cache_ts: dict[str, float] = {}
+        # Audit 2026-09-23: cap the in-process LLM response cache so a
+        # long-running evolution pass cannot leak memory. When the cache
+        # exceeds ``_MAX_CACHE_SIZE`` we evict the oldest entries (FIFO
+        # via ``_cache_ts``; an LRU variant would also be fine).
+        self._MAX_CACHE_SIZE = 256
         self._run_id: str | None = None
 
     # --- public ----------------------------------------------------------
@@ -1998,6 +2003,15 @@ class EvolutionConsolidator:
             return ""
         self._cache[cache_key] = reply
         self._cache_ts[cache_key] = now
+        # Bound the cache: drop oldest entries when we exceed the cap.
+        # Cheap O(n) walk; the cache holds at most _MAX_CACHE_SIZE so
+        # the walk is bounded too.
+        if len(self._cache) > self._MAX_CACHE_SIZE:
+            ordered = sorted(self._cache_ts.items(), key=lambda kv: kv[1])
+            evict_count = len(self._cache) - self._MAX_CACHE_SIZE
+            for old_key, _ in ordered[:evict_count]:
+                self._cache.pop(old_key, None)
+                self._cache_ts.pop(old_key, None)
         if kind == "cluster":
             stats.cluster_calls += 1
         elif kind == "wiki":

{loop_memory-0.4.8 → loop_memory-0.4.10}/loop_memory/jobs/graph.py

@@ -337,46 +337,62 @@ def subgraph_for(
 ) -> Subgraph:
     """Build a small subgraph relevant to ``query``.
 
-    1. Extract entities from the query.
-    2. Pull every relation (1 hop) that touches a query entity.
-    3. Look up the backing memory ids for each entity.
+    1. Extract entities from the query (seed set).
+    2. BFS up to ``max_hops`` edges from the seed set, walking
+       ``store.related_entities`` at each layer.
+    3. Look up the backing memory ids for each entity seen.
     4. Trim to ``max_nodes`` / ``max_edges``.
 
+    Audit 2026-09-23: previously the function ignored ``max_hops``
+    and always walked exactly one hop. The default is unchanged
+    (1 hop) so existing callers see no behaviour delta; callers
+    that explicitly pass ``max_hops >= 2`` now get the multi-hop
+    walk they asked for. ``max_hops`` is hard-capped at 8 so a typo
+    cannot fan out across the whole graph.
+
     Returns a :class:`Subgraph` dataclass so callers can render it
     however they like (Mermaid, JSON for the SDK, etc.).
     """
     from ..graph.extract import extract_entities
-    ents = [n for (n, _) in extract_entities(query) if n]
-    if not ents:
+    max_hops = max(1, min(int(max_hops or 1), 8))
+    seed_ents = [n for (n, _) in extract_entities(query) if n]
+    if not seed_ents:
         return Subgraph(nodes=[], edges=[], memory_ids=[])
     nodes: dict[str, dict[str, Any]] = {}
     edges: list[dict[str, Any]] = []
     memory_ids: set[str] = set()
-    for ent in ents:
-        info = store.entity_by_name(ent)
-        if info:
-            nodes[ent] = {
-                "name": ent,
-                "kind": info.get("kind") or "concept",
-                "weight": float(info.get("weight") or 0),
-                "mention_count": int(info.get("mention_count") or 0),
-            }
-        else:
-            nodes[ent] = {"name": ent, "kind": "concept", "weight": 0.5, "mention_count": 0}
-        for nb in store.related_entities(ent, limit=32):
-            if nb not in nodes:
-                nb_info = store.entity_by_name(nb) or {}
-                nodes[nb] = {
-                    "name": nb,
-                    "kind": nb_info.get("kind") or "concept",
-                    "weight": float(nb_info.get("weight") or 0),
-                    "mention_count": int(nb_info.get("mention_count") or 0),
-                }
-            edge = {"src": ent, "dst": nb, "kind": "related"}
-            if edge not in edges:
-                edges.append(edge)
-        for mid in store.memory_ids_for_entity(ent, limit=32):
+
+    def _record_node(name: str) -> None:
+        if name in nodes:
+            return
+        info = store.entity_by_name(name) or {}
+        nodes[name] = {
+            "name": name,
+            "kind": info.get("kind") or "concept",
+            "weight": float(info.get("weight") or 0),
+            "mention_count": int(info.get("mention_count") or 0),
+        }
+        for mid in store.memory_ids_for_entity(name, limit=32):
             memory_ids.add(mid)
+
+    frontier = list(seed_ents)
+    for ent in frontier:
+        _record_node(ent)
+    seen_edge: set[tuple[str, str]] = set()
+    for _ in range(max_hops):
+        if not frontier:
+            break
+        next_frontier: list[str] = []
+        for ent in frontier:
+            for nb in store.related_entities(ent, limit=32):
+                _record_node(nb)
+                key = (ent, nb)
+                if key in seen_edge:
+                    continue
+                seen_edge.add(key)
+                edges.append({"src": ent, "dst": nb, "kind": "related"})
+                next_frontier.append(nb)
+        frontier = next_frontier
     # Trim
     n_nodes = list(nodes.values())[:max_nodes]
     n_edges = edges[:max_edges]

{loop_memory-0.4.8 → loop_memory-0.4.10}/loop_memory/jobs/llm_consolidate.py

@@ -335,6 +335,10 @@ class LLMConsolidator:
         self._cache: dict[str, str] = {}  # batch hash -> LLM reply
         self._cache_ttl = 300.0
         self._cache_ts: dict[str, float] = {}
+        # Audit 2026-09-23: cap the in-process LLM response cache so a
+        # long-running consolidation pass cannot leak memory. Same FIFO
+        # eviction as ``EvolutionRunner._MAX_CACHE_SIZE``.
+        self._MAX_CACHE_SIZE = 256
 
     # --- public -----------------------------------------------------------
 
@@ -620,6 +624,16 @@ class LLMConsolidator:
                 ) or ""
                 self._cache[cache_key] = reply
                 self._cache_ts[cache_key] = now
+                # Bound the cache: drop oldest entries when we exceed
+                # the cap (FIFO via _cache_ts).
+                if len(self._cache) > self._MAX_CACHE_SIZE:
+                    ordered = sorted(
+                        self._cache_ts.items(), key=lambda kv: kv[1]
+                    )
+                    evict_count = len(self._cache) - self._MAX_CACHE_SIZE
+                    for old_key, _ in ordered[:evict_count]:
+                        self._cache.pop(old_key, None)
+                        self._cache_ts.pop(old_key, None)
                 stats.llm_calls += 1
             except Exception as e:
                 stats.notes.append(f"wiki llm error: {type(e).__name__}: {e}")
@@ -863,6 +877,16 @@ class LLMConsolidator:
                 stats.llm_calls += 1
                 self._cache[cache_key] = reply
                 self._cache_ts[cache_key] = now
+                # Bound the cache: drop oldest entries when we exceed
+                # the cap (FIFO via _cache_ts).
+                if len(self._cache) > self._MAX_CACHE_SIZE:
+                    ordered = sorted(
+                        self._cache_ts.items(), key=lambda kv: kv[1]
+                    )
+                    evict_count = len(self._cache) - self._MAX_CACHE_SIZE
+                    for old_key, _ in ordered[:evict_count]:
+                        self._cache.pop(old_key, None)
+                        self._cache_ts.pop(old_key, None)
             except Exception as e:
                 log.warning("LLM call failed: %s", e)
                 stats.notes.append(f"llm error in batch: {type(e).__name__}: {e}")

loop_memory-0.4.10/loop_memory/serve/routes/_shared.py

@@ -0,0 +1,196 @@
+"""Helpers shared across route modules.
+
+The original ``serve/app.py`` (3226 lines) had every route defined as a
+closure inside ``create_app``. To keep the central file small (audit O1)
+we lifted each route group into its own ``routes/<bucket>.py`` module
+and emit ``register(app, store, scheduler=None)``. Closures over
+``_memory_to_dict`` and ``_export_safe_segment`` still work because
+both are imported here under the same names.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Optional
+
+from ..handlers import (
+    memory_to_dict as _memory_to_dict,  # noqa: F401
+    session_to_dict as _session_to_dict,  # noqa: F401
+)
+
+
+
+
+_THINK_RE = re.compile(r"<(think|reasoning)>(.*?)</\1>", re.DOTALL)
+
+
+def _split_think(text: str) -> tuple[str, str]:
+    """Pull LLM thinking/reasoning blocks out of a model reply.
+
+    Several providers (MiniMax reasoning, Anthropic extended thinking)
+    emit a ``<think>...</think>`` or ``<reasoning>...</reasoning>``
+    block before the user-visible answer. We surface the block under a
+    separate field so the UI can render the report as Markdown while
+    still letting power users peek at the chain-of-thought in a
+    collapsed ``<details>``.
+    """
+    if not text:
+        return "", ""
+    thinking_parts = _THINK_RE.findall(text)
+    cleaned = _THINK_RE.sub("", text).strip()
+    thinking = "\n\n".join(p[1].strip() for p in thinking_parts if p[1].strip())
+    return cleaned, thinking
+
+
+def _export_safe_segment(text: str, *, fallback: str = "", kind: str = "line") -> str:
+    """Sanitise a user-controlled wiki field for the markdown export.
+
+    Audit M2: a malicious title ``"My\\n## Pwned"`` would otherwise
+    create a second ``## Pwned`` heading on re-import. ``title`` /
+    ``summary`` fields are collapsed to a single line and stripped of
+    any leading ``## `` prefix; body content (legitimate markdown) is
+    left alone.
+    """
+    if not text:
+        return fallback
+    s = text
+    if kind in ("title", "summary"):
+        s = re.sub(r"\s+", " ", s).strip()
+        s = re.sub(r"^#+\s*", "", s).strip()
+    return s or fallback
+
+
+# ---------------------------------------------------------------------------
+# Path safety (audit 2026-09-23)
+# ---------------------------------------------------------------------------
+# Five export / snapshot endpoints accept a user-supplied absolute
+# path. Before this helper shipped, every endpoint passed the path
+# straight through to ``Path(...).expanduser().resolve()`` with no
+# validation, which meant a caller could:
+#
+#   * write into ``/`` or ``~/.ssh`` via ``out_dir``
+#   * overwrite the live SQLite store by setting
+#     ``out_path`` to ``~/.loop_memory/loop_memory.db`` via
+#     ``POST /api/snapshot``
+#   * read any path with a valid snapshot header via
+#     ``POST /api/snapshot/restore``
+#
+# When the bearer token is unset (the local-only default) the auth
+# middleware does not enforce auth at all, so any process on the same
+# host — including a malicious MCP client — could exploit the gap.
+#
+# ``_safe_resolve_path`` closes the gap with three rules:
+#
+#   1. Reject any path that resolves to the live DB (its canonical
+#      location, the WAL sidecar, or the SHM sidecar).
+#   2. Reject any path inside a system / sensitive directory
+#      (``/System``, ``/usr``, ``/etc``, ``/var``, ``/private``,
+#      ``~/.ssh``, ``~/.aws``, ``~/.gnupg``). Each rule covers a real
+#      exfiltration / corruption vector observed in the wild for local
+#      AI tooling.
+#   3. Require the parent directory to exist for writes (so a typo
+#      doesn't silently materialise a path that later resolves into
+#      a sensitive root via symlink).
+#
+# ``kind="read"`` skips rule 3 (a read can describe a non-existent
+# file) but still applies rules 1 and 2.
+
+_FORBIDDEN_PREFIXES = (
+    "/etc", "/private/etc", "/var", "/private/var",
+    "/usr", "/bin", "/sbin", "/System", "/Library",
+    "/private/var/db", "/private/var/log",
+    "/private/var/root", "/private/var/run",
+    "/var/db", "/var/log", "/var/run",
+    "/dev", "/proc", "/sys",
+)
+# macOS resolves ``/tmp`` to ``/private/var/folders/<user>/T/`` and
+# shells routinely write there. We allow the per-user temp subtree
+# even though it starts with the otherwise-forbidden ``/private/var``.
+_ALLOWED_TEMP_SUBSTRINGS = (
+    "/var/folders/",   # macOS per-user temp
+    "/var/tmp/",       # BSD/Linux preserved temp
+    "/tmp/",           # Linux /tmp + macOS /private/tmp
+    "/private/tmp/",   # macOS /tmp
+    "/private/var/folders/",  # macOS per-user temp (resolved)
+)
+
+
+def _safe_resolve_path(
+    raw: str | Path,
+    *,
+    kind: str = "write",
+    live_db_path: str | Path | None = None,
+) -> Path:
+    """Return an absolute, validated Path or raise ``ValueError``.
+
+    ``kind`` is ``"write"`` (default) or ``"read"``. Writes also
+    require the parent directory to exist; reads don't.
+
+    ``live_db_path`` is the canonical SQLite path the running store
+    owns. If a caller hands us that path (or the WAL/SHM sidecars),
+    we refuse loudly instead of silently overwriting the live store.
+    """
+    if raw is None or (isinstance(raw, str) and not raw.strip()):
+        raise ValueError("path is required")
+    try:
+        resolved = Path(str(raw)).expanduser().resolve(strict=False)
+    except (OSError, RuntimeError) as e:
+        raise ValueError(f"could not resolve path: {e}") from e
+    s = str(resolved)
+
+    # Rule 1 — refuse the live DB + its WAL/SHM sidecars.
+    if live_db_path is not None:
+        try:
+            live_resolved = Path(str(live_db_path)).expanduser().resolve(strict=False)
+        except (OSError, RuntimeError):
+            live_resolved = None
+        if live_resolved is not None:
+            live_str = str(live_resolved)
+            for suffix in ("", "-wal", "-shm", "-journal"):
+                if s == live_str + suffix:
+                    raise ValueError(
+                        "refusing to write to the live SQLite store; "
+                        "use a different path (e.g. ~/.loop_memory/snapshots/)"
+                    )
+
+    # Rule 2 — refuse system / sensitive directories.
+    # Allow common per-user temp directories before applying the
+    # forbidden-prefix rule so ``/tmp`` (which resolves to
+    # ``/private/var/folders/...`` on macOS) still works.
+    is_temp = any(sub in s for sub in _ALLOWED_TEMP_SUBSTRINGS)
+    if not is_temp:
+        for prefix in _FORBIDDEN_PREFIXES:
+            if s == prefix.rstrip("/") or s.startswith(prefix + "/"):
+                raise ValueError(
+                    f"refusing to {'write to' if kind == 'write' else 'read from'} "
+                    f"system directory {prefix!r}"
+                )
+    home = Path.home()
+    home_str = str(home)
+    for sensitive in (".ssh", ".aws", ".gnupg", ".config/gh", ".npmrc", ".zsh_history", ".bash_history"):
+        forbidden = home_str + "/" + sensitive
+        if s == forbidden or s.startswith(forbidden + "/"):
+            raise ValueError(
+                f"refusing to {'write to' if kind == 'write' else 'read from'} "
+                f"sensitive path {sensitive!r}"
+            )
+
+    # Rule 3 — writes require an existing parent (catches typos that
+    # could later resolve into a sensitive root via symlink).
+    if kind == "write":
+        parent = resolved.parent
+        if not parent.exists():
+            raise ValueError(
+                f"parent directory does not exist: {parent} "
+                "(create it first; refusing to materialise arbitrary paths)"
+            )
+
+    return resolved
+
+
+__all__ = [
+    "_memory_to_dict",
+    "_session_to_dict",
+    "_export_safe_segment",
+    "_safe_resolve_path",
+]

{loop_memory-0.4.8 → loop_memory-0.4.10}/loop_memory/serve/routes/export.py

@@ -18,21 +18,30 @@ from ...storage.sqlite_store import MemoryStore
 from ._shared import _memory_to_dict, _export_safe_segment
 
 
-def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None) -> None:
+def register(app, store, scheduler=None):
     """Mount every route in this bucket onto ``app``.
 
     ``store`` and ``scheduler`` are captured in the route closures so
     the function bodies stay byte-identical to the pre-split layout.
     """
+    # Audit 2026-09-23: cache the live DB path so each route can hand
+    # it to ``_safe_resolve_path`` (rule 1 refuses writes to the live
+    # DB). Pre-computing here keeps the per-request path cheap.
+    _live_db_path = str(store.path)
+    from ._shared import _safe_resolve_path as _safe_path
     @app.post("/api/v1/export")
     def v1_export(body: dict):
         from ...export import export_bundle
         out_dir = (body.get("out_dir") or "").strip()
         if not out_dir:
             raise HTTPException(400, "out_dir is required")
+        try:
+            safe_dir = _safe_path(out_dir, kind="write", live_db_path=_live_db_path)
+        except ValueError as e:
+            raise HTTPException(400, str(e))
         try:
             r = export_bundle(
-                store, out_dir,
+                store, str(safe_dir),
                 agent_id=body.get("agent_id") or None,
                 user_id=body.get("user_id") or None,
                 scope=body.get("scope") or "global",
@@ -49,9 +58,13 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None)
         in_dir = (body.get("in_dir") or "").strip()
         if not in_dir:
             raise HTTPException(400, "in_dir is required")
+        try:
+            safe_dir = _safe_path(in_dir, kind="read", live_db_path=_live_db_path)
+        except ValueError as e:
+            raise HTTPException(400, str(e))
         try:
             r = import_bundle(
-                store, in_dir,
+                store, str(safe_dir),
                 agent_id=body.get("agent_id") or None,
                 user_id=body.get("user_id") or None,
                 dry_run=bool(body.get("dry_run", False)),
@@ -68,13 +81,19 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None)
 
         Body: ``{"out_path": "/path/to/file.memory.sqlite"}``. Returns
         the summary dict from ``loop_memory.storage.snapshot.snapshot``.
+        Audit 2026-09-23: ``out_path`` is rejected if it points at the
+        live store or a system / sensitive directory.
         """
         from ...storage.snapshot import snapshot as _snapshot
         out = (body.get("out_path") or "").strip()
         if not out:
             raise HTTPException(400, "out_path is required")
         try:
-            return _snapshot(store, out)
+            safe_out = _safe_path(out, kind="write", live_db_path=_live_db_path)
+        except ValueError as e:
+            raise HTTPException(400, str(e))
+        try:
+            return _snapshot(store, str(safe_out))
         except Exception as e:
             raise HTTPException(500, f"snapshot failed: {e}")
 
@@ -86,13 +105,19 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None)
         the summary dict from ``loop_memory.storage.snapshot.restore``.
         Refuses wrong-magic files with a 400 so the dashboard surfaces
         the error clearly instead of corrupting the live store.
+        Audit 2026-09-23: ``in_path`` is rejected if it points at the
+        live store or a system / sensitive directory.
         """
         from ...storage.snapshot import restore as _restore
         in_path = (body.get("in_path") or "").strip()
         if not in_path:
             raise HTTPException(400, "in_path is required")
         try:
-            return _restore(store, in_path)
+            safe_in = _safe_path(in_path, kind="read", live_db_path=_live_db_path)
+        except ValueError as e:
+            raise HTTPException(400, str(e))
+        try:
+            return _restore(store, str(safe_in))
         except FileNotFoundError as e:
             raise HTTPException(404, str(e))
         except ValueError as e: