agent-memory-brain 0.2.0__py3-none-any.whl

devmem/git_sync.py

@@ -0,0 +1,261 @@
+"""Private Git memory sync.  State is deliberately kept outside SQLite."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .db import connection, now, save_memory, update_memory
+from .filelock import acquire, release
+from .messages import guard
+from .procs import executable
+
+_KINDS = {"note", "decision", "preference", "snippet", "todo"}
+
+
+def _path(name: str, default: str) -> Path:
+    return Path(os.environ.get(name, default)).expanduser()
+
+
+def config_path() -> Path: return _path("DEVMEM_GIT_SYNC", "~/.devmem/git-sync.json")
+def state_path() -> Path: return _path("DEVMEM_GIT_SYNC_STATE", "~/.devmem/git-sync-state.json")
+def key_path() -> Path: return _path("DEVMEM_GIT_SYNC_KEY", "~/.devmem/git-sync-key")
+def repo_path() -> Path: return _path("DEVMEM_GIT_DIR", "~/.devmem/git-memories")
+def lock_path() -> Path: return _path("DEVMEM_GIT_SYNC_LOCK", "~/.devmem/git-sync.lock")
+
+
+def _read(path: Path, fallback):
+    try:
+        with path.open(encoding="utf-8") as f: return json.load(f)
+    except FileNotFoundError: return fallback
+    except (OSError, ValueError) as exc: raise ValueError(f"invalid {path.name}: {exc}") from exc
+
+
+def config() -> dict:
+    data = _read(config_path(), {})
+    if not isinstance(data, dict): raise ValueError("git sync config must be an object")
+    return data
+
+
+def _atomic(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, separators=(",", ":")); f.write("\n"); f.flush(); os.fsync(f.fileno())
+        os.chmod(temp, 0o600); os.replace(temp, path)
+    finally:
+        if os.path.exists(temp): os.unlink(temp)
+
+
+def write_config(data: dict) -> None: _atomic(config_path(), data)
+
+
+def _state() -> dict:
+    data = _read(state_path(), {"memories": {}, "out_of_sync": [], "last_sync": None, "last_error": None, "pushed": 0, "pulled": 0})
+    if not isinstance(data, dict): raise ValueError("git sync state must be an object")
+    data.setdefault("memories", {}); data.setdefault("out_of_sync", [])
+    return data
+
+
+def _git_env(cfg: dict) -> dict:
+    env = os.environ.copy()
+    if not os.environ.get("DEVMEM_GIT_REMOTE"):
+        key = key_path()
+        known = key.with_name("git-sync-known_hosts")
+        env["GIT_SSH_COMMAND"] = f"ssh -i {key} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile={known}"
+    return env
+
+
+def _run(cfg: dict, *args: str, cwd: Path | None = None) -> str:
+    result = subprocess.run([executable("git"), *args], cwd=cwd, env=_git_env(cfg), text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if result.returncode: raise RuntimeError((result.stderr or result.stdout or "git failed").strip()[:500])
+    return result.stdout.strip()
+
+
+def _remote(cfg: dict) -> str:
+    injected = os.environ.get("DEVMEM_GIT_REMOTE")
+    if injected: return injected
+    repo = cfg.get("repo", "")
+    if not re.fullmatch(r"[^/\s]+/[^/\s]+", repo): raise ValueError("repo must be owner/name")
+    return f"ssh://git@ssh.github.com:443/{repo}.git" if cfg.get("ssh_port") == 443 else f"git@github.com:{repo}.git"
+
+
+def _project(value: str | None) -> str:
+    return Path(value).name if value else "global"
+
+
+def _tags(value: str) -> list[str]: return [x.strip() for x in value.split(",") if x.strip()]
+def _scope(row: dict, cfg: dict) -> bool:
+    return _project(row.get("project")) in cfg.get("projects", []) or (not row.get("project") and cfg.get("global_tag") in _tags(row.get("tags") or ""))
+
+
+def in_scope(row: dict) -> bool:
+    try: return _scope(row, config())
+    except ValueError: return False
+
+
+def _slug(value: str) -> str:
+    result = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    return result[:60] or "memory"
+
+
+def _frontmatter(meta: dict, content: str) -> str:
+    tags = ", ".join(meta["tags"])
+    review = f"review_after: {meta['review_after']}\n" if meta.get("review_after") else ""
+    ident = f"id: {meta['id']}\n" if meta.get("id") is not None else ""
+    updated = f"updated: {meta['updated']}\n" if meta.get("updated") else ""
+    return f"---\n{ident}kind: {meta['kind']}\ntitle: {meta['title']}\nproject: {meta['project']}\ntags: [{tags}]\n{updated}{review}---\n{content.rstrip()}\n"
+
+
+def _parse(path: Path) -> tuple[dict, str]:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"): raise ValueError("frontmatter is required")
+    head, sep, content = text[4:].partition("\n---\n")
+    if not sep: raise ValueError("frontmatter is not closed")
+    data = {}
+    for line in head.splitlines():
+        key, mark, value = line.partition(":")
+        if not mark: raise ValueError("invalid frontmatter")
+        value = value.strip(); data[key.strip()] = value
+    data["tags"] = [x.strip() for x in data.get("tags", "[]").strip("[]").split(",") if x.strip()]
+    if data.get("kind", "note") not in _KINDS: raise ValueError("invalid kind")
+    data["kind"] = data.get("kind", "note"); data["project"] = data.get("project", "global")
+    return data, content.rstrip("\n")
+
+
+def _blob(path: Path) -> str:
+    data = path.read_bytes(); return hashlib.sha1(f"blob {len(data)}\0".encode() + data).hexdigest()
+
+
+def _write_memory(root: Path, row: dict) -> Path:
+    folder = _project(row.get("project")); path = root / "memories" / folder / f"{row['id']}-{_slug(row['title'])}.md"
+    guard(row["content"], row["title"])
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(_frontmatter({"id": row["id"], "kind": row["kind"], "title": row["title"], "project": folder, "tags": _tags(row["tags"]), "updated": row["updated_at"].replace("+00:00", "Z"), "review_after": row.get("review_after")}, row["content"]), encoding="utf-8")
+    return path
+
+
+def _layout(root: Path) -> None:
+    readme = root / "README.md"; agents = root / "AGENTS.md"
+    if not readme.exists(): readme.write_text("# devmem memories\n\nPersonal memories synchronized by devmem.\n", encoding="utf-8")
+    if not agents.exists(): agents.write_text("# Memory instructions\n\nSearch before editing. Add new memories in `inbox/`; edit existing files in place and bump `updated`. Never put secrets here.\n", encoding="utf-8")
+    (root / "memories").mkdir(exist_ok=True); (root / "inbox").mkdir(exist_ok=True)
+
+
+def _ensure_repo(cfg: dict) -> Path:
+    root = repo_path()
+    if not (root / ".git").is_dir():
+        root.parent.mkdir(parents=True, exist_ok=True); _run(cfg, "clone", _remote(cfg), str(root))
+    _run(cfg, "config", "user.name", str(cfg.get("author_name", "devmem")), cwd=root)
+    _run(cfg, "config", "user.email", str(cfg.get("author_email", "devmem@localhost")), cwd=root)
+    # A run that failed before committing leaves files behind; the DB and the remote are the truth, so drop them.
+    try: _run(cfg, "reset", "--hard", cwd=root)
+    except RuntimeError: pass  # no commit yet
+    _run(cfg, "clean", "-fd", cwd=root)
+    _run(cfg, "fetch", "origin", cwd=root)
+    branch = cfg.get("branch", "main")
+    try: _run(cfg, "rev-parse", "--verify", f"origin/{branch}", cwd=root)
+    except RuntimeError:
+        _run(cfg, "symbolic-ref", "HEAD", f"refs/heads/{branch}", cwd=root)  # an empty remote: first commit goes to the configured branch
+        return root
+    try: _run(cfg, "rebase", f"origin/{branch}", cwd=root)
+    except RuntimeError as exc:
+        _run(cfg, "rebase", "--abort", cwd=root)
+        raise RuntimeError("git conflict: " + str(exc)) from exc
+    return root
+
+
+def _commit(cfg: dict, root: Path, summary: dict, dry_run: bool) -> bool:
+    status = _run(cfg, "status", "--porcelain", cwd=root)
+    if not status: return False
+    if dry_run: return True
+    _run(cfg, "add", "-A", cwd=root)
+    _run(cfg, "commit", "-m", f"devmem sync: +{summary['pushed']} ~{summary['pulled']} -{summary['deleted']}", cwd=root)
+    try: _run(cfg, "push", "origin", cfg.get("branch", "main"), cwd=root)
+    except RuntimeError:
+        _run(cfg, "fetch", "origin", cwd=root); _run(cfg, "rebase", f"origin/{cfg.get('branch', 'main')}", cwd=root); _run(cfg, "push", "origin", cfg.get("branch", "main"), cwd=root)
+    return True
+
+
+def sync(*, dry_run: bool = False) -> dict:
+    cfg = config(); result = {"pushed": 0, "pulled": 0, "deleted": 0, "errors": [], "out_of_sync": []}
+    if not cfg.get("enabled"): return {**result, "disabled": True}
+    if dry_run:
+        with connection() as conn:
+            result["pushed"] = sum(1 for row in conn.execute("SELECT * FROM memories") if _scope(dict(row), cfg))
+        result["dry_run"] = True
+        return result
+    lock_path().parent.mkdir(parents=True, exist_ok=True)
+    with lock_path().open("a+") as lock:
+        try: acquire(lock)
+        except BlockingIOError: return {**result, "locked": True}
+        state = _state()
+        try:
+            root = _ensure_repo(cfg); _layout(root)
+            files = {str(path.relative_to(root)): path for path in (root / "memories").glob("**/*.md")}
+            with connection() as conn:
+                rows = {str(row["id"]): dict(row) for row in conn.execute("SELECT * FROM memories").fetchall()}
+                known = dict(state["memories"])  # only saved when the whole run succeeds
+                for ident, prior in list(known.items()):
+                    path = root / prior["path"]
+                    if ident not in rows:
+                        if path.exists(): path.unlink(); result["deleted"] += 1
+                        known.pop(ident, None); continue
+                    if not path.exists():
+                        result["out_of_sync"].append(int(ident)); continue
+                for ident, row in rows.items():
+                    if not _scope(row, cfg):
+                        prior = known.pop(ident, None)
+                        if prior and (root / prior["path"]).exists(): (root / prior["path"]).unlink(); result["deleted"] += 1
+                        continue
+                    prior = known.get(ident); path = root / prior["path"] if prior else None
+                    if prior and ident in result["out_of_sync"]: continue
+                    if not prior or not path or not path.exists():
+                        try: path = _write_memory(root, row); result["pushed"] += 1
+                        except ValueError as exc: result["errors"].append(f"#{ident}: {exc}"); continue
+                    else:
+                        sha = _blob(path); local_changed = row["updated_at"] != prior.get("db_updated_at"); file_changed = sha != prior.get("blob")
+                        if file_changed:
+                            try: meta, content = _parse(path); guard(content, meta.get("title"))
+                            except (OSError, ValueError) as exc: result["errors"].append(f"{prior['path']}: {exc}"); continue
+                            remote_newer = not local_changed or meta.get("updated", "") > row["updated_at"].replace("+00:00", "Z")
+                            if remote_newer:
+                                update_memory(conn, int(ident), content=content, title=meta.get("title", row["title"]), kind=meta["kind"], tags=", ".join(meta["tags"]), review_after=meta.get("review_after") or "")
+                                row = dict(conn.execute("SELECT * FROM memories WHERE id=?", (ident,)).fetchone()); rows[ident] = row; result["pulled"] += 1
+                            else:
+                                if local_changed:  # both sides edited: the losing remote version goes into history
+                                    conn.execute("INSERT INTO memory_revisions(memory_id,project,kind,title,content,tags,pinned,created_at,op,revised_at) VALUES (?,?,?,?,?,?,?,?,'update',?)",
+                                                 (int(ident), row["project"], meta["kind"], meta.get("title") or row["title"], content, ", ".join(meta["tags"]), row["pinned"], row["created_at"], now()))
+                                try: _write_memory(root, row); result["pushed"] += 1
+                                except ValueError as exc: result["errors"].append(f"#{ident}: {exc}"); continue
+                        elif local_changed:
+                            try: _write_memory(root, row); result["pushed"] += 1
+                            except ValueError as exc: result["errors"].append(f"#{ident}: {exc}"); continue
+                    known[ident] = {"path": str(path.relative_to(root)), "blob": _blob(path), "db_updated_at": row["updated_at"]}
+                for inbox in (root / "inbox").glob("*.md"):
+                    try:
+                        meta, content = _parse(inbox); guard(content, meta.get("title")); project = meta["project"]
+                        tags = meta["tags"] or ([cfg.get("global_tag", "personal")] if project == "global" else [])
+                        memory_id = save_memory(conn, content=content, title=meta.get("title") or content[:80], kind=meta["kind"], tags=", ".join(tags), project=None if project == "global" else project, review_after=meta.get("review_after") or "", source_agent="git-sync")
+                        row = dict(conn.execute("SELECT * FROM memories WHERE id=?", (memory_id,)).fetchone()); path = _write_memory(root, row); inbox.unlink(); known[str(memory_id)] = {"path": str(path.relative_to(root)), "blob": _blob(path), "db_updated_at": row["updated_at"]}; result["pulled"] += 1
+                        if not _scope(row, cfg): result["errors"].append(f"{inbox.name}: imported outside allowlist")
+                    except (OSError, ValueError) as exc: result["errors"].append(f"{inbox.name}: {exc}")
+            if not dry_run: _commit(cfg, root, result, False)
+            state.update({"memories": known, "out_of_sync": result["out_of_sync"], "last_sync": now(), "last_error": "; ".join(result["errors"]) or None, "pushed": result["pushed"], "pulled": result["pulled"]})
+            if not dry_run: _atomic(state_path(), state)
+        except Exception as exc:
+            result["errors"].append(str(exc)); state["last_error"] = str(exc); state["last_sync"] = now()
+            if not dry_run: _atomic(state_path(), state)
+        finally: release(lock)
+    return result
+
+
+def status() -> dict:
+    state = _state(); cfg = config()
+    return {"enabled": bool(cfg.get("enabled")), "repo": cfg.get("repo"), "last_sync": state.get("last_sync"), "pushed": state.get("pushed", 0), "pulled": state.get("pulled", 0), "error": state.get("last_error"), "out_of_sync": state.get("out_of_sync", [])}

devmem/guard.py

@@ -0,0 +1,214 @@
+"""Fast, stdlib-only rule guard for Claude PreToolUse hooks."""
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import re
+import shlex
+import sqlite3
+import sys
+from pathlib import Path
+
+from .hook_log import guard_log
+from .projects import project_for_cwd
+
+_FIELDS = {"tool", "command", "path", "action"}
+_ASSIGNMENT = re.compile(r"""^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+)+""")
+_SEGMENT = re.compile(r"&&|\|\||;|\||&|\n|\$\(|[()`{}]")
+_TOKEN_SPLIT = re.compile(r"[\s<>;|&()`]+")
+_TOOL = re.compile(r"\*|[A-Za-z][A-Za-z0-9_-]*")
+_NEAR_GUARD = re.compile(r"^\W*guard\s*:", re.I)
+_KNOWN_TOOLS = {"Bash", "Read", "Edit", "Write", "NotebookEdit", "Glob", "Grep", "WebFetch", "WebSearch", "Agent", "Task", "TodoWrite"}
+
+
+def parse_rules(content: str) -> tuple[list[dict], list[dict], list[dict]]:
+    """Return valid GUARD rules and invalid-line reports from one memory."""
+    rules, invalid, notices = [], [], []
+    for line in content.splitlines():
+        if not line.startswith("GUARD:"):
+            if _NEAR_GUARD.match(line): invalid.append({"line": line, "reason": "GUARD: must start the line, in capitals"})
+            continue
+        text = line.removeprefix("GUARD:").strip()
+        try:
+            rule = json.loads(text)
+        except json.JSONDecodeError:
+            invalid.append({"line": line, "reason": "invalid JSON"}); continue
+        if not isinstance(rule, dict):
+            invalid.append({"line": line, "reason": "must be a JSON object"}); continue
+        unknown = set(rule) - _FIELDS
+        if unknown:
+            invalid.append({"line": line, "reason": "unknown field " + sorted(unknown)[0]}); continue
+        if not isinstance(rule.get("tool"), str) or not _TOOL.fullmatch(rule["tool"]):
+            invalid.append({"line": line, "reason": "invalid tool name"}); continue
+        if rule.get("action") not in ("deny", "ask"):
+            invalid.append({"line": line, "reason": "action must be deny or ask"}); continue
+        if any(key in rule and not isinstance(rule[key], str) for key in ("command", "path")):
+            invalid.append({"line": line, "reason": "command and path must be strings"}); continue
+        if any(key in rule and not rule[key] for key in ("command", "path")):
+            invalid.append({"line": line, "reason": "command and path must be non-empty"}); continue
+        if "command" in rule and rule["tool"] != "Bash":
+            invalid.append({"line": line, "reason": "command is only valid for Bash"}); continue
+        if rule["tool"] not in _KNOWN_TOOLS and not rule["tool"].startswith("mcp__") and rule["tool"] != "*":
+            notices.append({"line": line, "reason": f"tool {rule['tool']} is not a known Claude tool (matching is case-sensitive)"})
+            known = next((name for name in _KNOWN_TOOLS if name.lower() == rule["tool"].lower()), None)
+            if known: notices.append({"line": line, "reason": f"did you mean {known}?"})
+        rules.append(rule)
+    return rules, invalid, notices
+
+
+def parse_text_rules(content: str) -> tuple[list[str], list[dict]]:
+    """Return plain-language RULE lines and malformed-line reports from one memory."""
+    rules, invalid = [], []
+    for line in content.splitlines():
+        if not line.startswith("RULE:"):
+            continue
+        if not line.startswith("RULE: ") or not line.removeprefix("RULE: ").strip():
+            invalid.append({"line": line, "reason": "RULE: must be followed by a sentence"})
+            continue
+        rules.append(line.removeprefix("RULE: ").strip())
+    return rules, invalid
+
+
+def _rows(conn: sqlite3.Connection, cwd: str | None, all_scopes: bool = False) -> list[sqlite3.Row]:
+    project = project_for_cwd(cwd)
+    scope, params = "1=1", ()
+    if not all_scopes: scope, params = "(m.project IS NULL OR m.project=?)", (project,)
+    return conn.execute("""SELECT m.id,m.title,m.content,m.project FROM memories m
+        WHERE """ + scope + """ AND NOT EXISTS
+        (SELECT 1 FROM memory_links l WHERE l.to_id=m.id AND l.type='supersedes')
+        AND (instr(m.content,'GUARD:') > 0 OR instr(m.content,'RULE:') > 0) ORDER BY m.id""", params).fetchall()
+
+
+def rules_data(conn: sqlite3.Connection, cwd: str | None = None, *, all_scopes: bool = False) -> dict:
+    """Return GUARD and plain-text rules from the applicable non-superseded memories."""
+    rules, text_rules, invalid, notices = [], [], [], []
+    for row in _rows(conn, cwd, all_scopes):
+        parsed, bad, note = parse_rules(row["content"])
+        text, text_bad = parse_text_rules(row["content"])
+        rules.extend({**rule, "id": row["id"], "title": row["title"]} for rule in parsed)
+        text_rules.extend({"text": item, "id": row["id"], "title": row["title"]} for item in text)
+        invalid.extend({**item, "id": row["id"], "title": row["title"]} for item in bad)
+        invalid.extend({**item, "id": row["id"], "title": row["title"]} for item in text_bad)
+        notices.extend({**item, "id": row["id"], "title": row["title"]} for item in note)
+    return {"rules": rules, "text_rules": text_rules, "invalid": invalid, "notices": notices, "project": project_for_cwd(cwd) if cwd else None}
+
+
+def warnings(content: str) -> list[str]:
+    """Human-readable warnings for malformed GUARD and RULE lines without rejecting a memory."""
+    parsed = parse_rules(content)
+    _, text_invalid = parse_text_rules(content)
+    return [f"{item['line']}: {item['reason']}" for item in parsed[1] + parsed[2] + text_invalid]
+
+
+def _glob_variants(pattern: str) -> list[str]:
+    """Each `**/` may also match zero directories: try every combination of dropping them (only all-or-none past six, to bound the blowup)."""
+    parts = pattern.split("**/")
+    if len(parts) > 7: return [pattern, pattern.replace("**/", "")]
+    variants = [parts[0]]
+    for part in parts[1:]: variants = [v + glue + part for v in variants for glue in ("**/", "")]
+    return variants
+
+
+def _glob(pattern: str, value: str) -> bool:
+    return any(fnmatch.fnmatchcase(value, variant) for variant in _glob_variants(pattern))
+
+
+def _paths(value: str, cwd: str | None) -> list[str]:
+    base = cwd or os.getcwd()
+    absolute = os.path.abspath(os.path.join(base, os.path.expandvars(os.path.expanduser(value))))
+    return [value, absolute]
+
+
+def _path_matches(pattern: str, value: str, cwd: str | None) -> bool:
+    paths = _paths(value, cwd)
+    if not pattern.startswith(("/", "~", "**/")):
+        for directory in (project_for_cwd(cwd), cwd):
+            if directory:
+                try:
+                    if os.path.commonpath((paths[1], os.path.abspath(directory))) == os.path.abspath(directory):
+                        paths.append(os.path.relpath(paths[1], directory))
+                except ValueError: pass
+    return any(_glob(pattern, path) for path in paths)
+
+
+def _bash_commands(command: str) -> list[str]:
+    pieces = [command, *(part.strip() for part in _SEGMENT.split(command) if part.strip())]
+    result = []
+    for piece in pieces:
+        value = _ASSIGNMENT.sub("", piece).strip()
+        while True:
+            prior = value
+            value = re.sub(r"^(?:then|do|else|elif|!|time|nohup|command|exec)\s+", "", value)
+            value = re.sub(r"^sudo(?:(?:\s+--\S+)|(?:\s+-(?:u|g|h|p|C|T)\s+\S+)|(?:\s+-\S+))*\s+", "", value)
+            value = re.sub(r"^nice(?:\s+-n\s+\S+)?\s+", "", value)
+            value = re.sub(r"^timeout(?:\s+-\S+)*(?:\s+\S+)?\s+", "", value)
+            value = re.sub(r"^env(?:\s+-\S+|\s+[A-Za-z_][A-Za-z0-9_]*=\S+)*\s+", "", value)
+            if value == prior: break
+        result.extend((piece, value, re.sub(r"\s+", " ", value).strip()))
+    return result
+
+
+def _tokens(command: str) -> list[str]:
+    """Raw tokens plus shell-unquoted ones, so `cat '.env'`, `cat<.env` and `--file=.env` are seen too."""
+    raw = _TOKEN_SPLIT.split(command)
+    try: unquoted = shlex.split(_TOKEN_SPLIT.sub(" ", command))
+    except ValueError: unquoted = []
+    tokens = [token.strip("'\"") for token in raw + unquoted if token.strip("'\"")]
+    return tokens + [token.rsplit("=", 1)[1] for token in tokens if "=" in token and not token.endswith("=")]
+
+
+def matches(rule: dict, tool_name: str, tool_input: dict, cwd: str | None) -> bool:
+    if rule["tool"] not in ("*", tool_name):
+        return False
+    command = tool_input.get("command") if isinstance(tool_input, dict) else None
+    if "command" in rule:
+        if tool_name != "Bash" or not isinstance(command, str) or not any(_glob(rule["command"], item) for item in _bash_commands(command)):
+            return False
+    path = next((tool_input[key] for key in ("file_path", "notebook_path", "path") if isinstance(tool_input.get(key), str)), None) if isinstance(tool_input, dict) else None
+    if "path" in rule:
+        path_match = isinstance(path, str) and _path_matches(rule["path"], path, cwd)
+        token_match = tool_name == "Bash" and isinstance(command, str) and any(_path_matches(rule["path"], token, cwd) for token in _tokens(command))
+        if not path_match and not token_match:
+            return False
+    return True
+
+
+def evaluate(data: dict, payload: dict) -> tuple[str, list[dict]]:
+    """Return deny, ask, or none and all rules at the winning level."""
+    tool_name, tool_input, cwd = payload.get("tool_name"), payload.get("tool_input"), payload.get("cwd")
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        return "none", []
+    matched = []
+    for rule in data["rules"]:
+        try:
+            if matches(rule, tool_name, tool_input, cwd if isinstance(cwd, str) else None): matched.append(rule)
+        except Exception as exc:
+            guard_log(f"guard rule #{rule.get('id', '?')} failed: {type(exc).__name__}: {exc}", db_path=os.environ.get("DEVMEM_DB", "~/.devmem/devmem.db"), tool_name=tool_name, cwd=cwd if isinstance(cwd, str) else None)
+    action = "deny" if any(rule["action"] == "deny" for rule in matched) else "ask" if matched else "none"
+    return action, [rule for rule in matched if rule["action"] == action]
+
+
+def readonly_rules(cwd: str | None = None) -> dict:
+    path = Path(os.environ.get("DEVMEM_DB", "~/.devmem/devmem.db")).expanduser().resolve()
+    uri = path.as_uri() + "?mode=ro"
+    with sqlite3.connect(uri, uri=True, timeout=0.5) as conn:
+        conn.row_factory = sqlite3.Row
+        return rules_data(conn, cwd)
+
+
+def hook() -> None:
+    """Run quietly and fail open for Claude's PreToolUse hook; errors go to the guard log."""
+    try:
+        payload = json.load(sys.stdin)
+        if not isinstance(payload, dict):
+            raise ValueError("hook input is not an object")
+        action, matched = evaluate(readonly_rules(payload.get("cwd")), payload)
+        if action == "none":
+            return
+        reason = "; ".join(f"#{rule['id']}: {rule['title']}" for rule in matched)
+        print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": action,
+                                                  "permissionDecisionReason": "devmem rule " + reason}}, separators=(",", ":")))
+    except Exception as exc:
+        payload = locals().get("payload", {})
+        guard_log(f"guard hook failed: {type(exc).__name__}: {exc}", db_path=os.environ.get("DEVMEM_DB", "~/.devmem/devmem.db"), tool_name=str(payload.get("tool_name", "")) if isinstance(payload, dict) else "", cwd=payload.get("cwd") if isinstance(payload, dict) and isinstance(payload.get("cwd"), str) else None)

devmem/hook_log.py

@@ -0,0 +1,49 @@
+"""Small hook-safe maintenance logger."""
+from __future__ import annotations
+
+import os
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+
+def _maintain_log() -> Path:
+    return Path(os.environ.get("DEVMEM_MAINTAIN_LOG", "~/.devmem/maintain.log")).expanduser()
+
+
+def _open_maintain_log():
+    """Append handle for detached maintenance output; rotated at 1 MB so it cannot grow without bound."""
+    path = _maintain_log(); path.parent.mkdir(parents=True, exist_ok=True)
+    if path.is_file() and path.stat().st_size > 1_000_000: path.replace(path.with_name(path.name + ".1"))
+    return open(path, "ab")
+
+
+def _log(message: str) -> None:
+    try:
+        with _open_maintain_log() as log: log.write(f"{datetime.now(UTC).isoformat()} {message}\n".encode())
+    except OSError:
+        pass
+
+
+def _guard_log() -> Path:
+    return Path(os.environ.get("DEVMEM_GUARD_LOG", "~/.devmem/guard.log")).expanduser()
+
+
+def guard_log(message: str, *, db_path: str, tool_name: str, cwd: str | None) -> None:
+    """Append a rate-limited guard failure without affecting the hook."""
+    try:
+        path = _guard_log(); state_path = path.with_name(path.name + ".state.json")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try: state = json.loads(state_path.read_text(encoding="utf-8"))
+        except Exception: state = {}
+        stamp = datetime.now(UTC).timestamp()
+        if stamp - float(state.get(message, 0)) < 600: return
+        state[message] = stamp
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+        try:
+            if path.is_file() and path.stat().st_size > 1_000_000: path.replace(path.with_name(path.name + ".1"))
+        except FileNotFoundError: pass
+        with open(path, "ab") as log:
+            log.write(f"{datetime.now(UTC).isoformat()} db={db_path} tool={tool_name} cwd={cwd or ''} {message}\n".encode(errors="replace"))
+    except Exception:
+        pass

devmem/ingest/__init__.py

@@ -0,0 +1 @@
+"""Parsers and incremental log ingestion."""

devmem/ingest/claude.py

@@ -0,0 +1,87 @@
+"""Claude Code JSONL parsing (pure functions deliberately accept synthetic logs)."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterator
+
+SUMMARY_MAX = 120
+# Only short, model-written hints are kept.  Never commands, file contents, prompts or edit strings.
+SUMMARY_KEYS = ("description", "file_path", "path", "pattern")
+
+
+def safe_summary(tool_input: Any) -> str:
+    if not isinstance(tool_input, dict):
+        return ""
+    for key in SUMMARY_KEYS:
+        value = tool_input.get(key)
+        if isinstance(value, str) and value.strip():
+            text = " ".join(value.split())
+            return text if len(text) <= SUMMARY_MAX else text[: SUMMARY_MAX - 1] + "…"
+    return ""
+
+
+def _str(value) -> str | None:
+    """Logs are not trusted to be well-typed: a dict where a string belongs would make SQLite reject the whole file."""
+    return value if isinstance(value, str) and value else None
+
+
+def _usage(obj: dict[str, Any]) -> dict[str, Any] | None:
+    message = obj.get("message") or {}
+    if not isinstance(message, dict):
+        return None
+    usage = message.get("usage")
+    if not isinstance(usage, dict):
+        return None
+    details = usage.get("output_tokens_details") or {}
+    return {
+        "agent": "claude",
+        "session_id": _str(obj.get("sessionId")), "project": _str(obj.get("cwd")),
+        "model": _str(message.get("model")) or "claude", "ts": _str(obj.get("timestamp")),
+        "input_tokens": int(usage.get("input_tokens", 0) or 0),
+        "output_tokens": int(usage.get("output_tokens", 0) or 0),
+        "cache_read_tokens": int(usage.get("cache_read_input_tokens", 0) or 0),
+        "cache_write_tokens": int(usage.get("cache_creation_input_tokens", 0) or 0),
+        "reasoning_tokens": int(details.get("thinking_tokens", 0) or 0),
+        "dedup_key": (obj.get("requestId"), message.get("id")),
+    }
+
+
+def _activities(obj: dict[str, Any]) -> list[dict[str, Any]]:
+    # Only real assistant turns: other record types (e.g. request replays) repeat old messages without timestamps.
+    if obj.get("type") != "assistant":
+        return []
+    message = obj.get("message") or {}
+    content = message.get("content") if isinstance(message, dict) else None
+    if not isinstance(content, list):
+        return []
+    agent = "claude-subagent" if obj.get("isSidechain") is True else "claude"
+    events = []
+    for item in content:
+        if isinstance(item, dict) and item.get("type") == "tool_use":
+            events.append({
+                "agent": agent, "session_id": _str(obj.get("sessionId")), "project": _str(obj.get("cwd")),
+                "ts": _str(obj.get("timestamp")), "kind": "tool", "name": str(item.get("name") or "tool")[:80],
+                "summary": safe_summary(item.get("input")),
+            })
+    return events
+
+
+def parse_record(line: str) -> tuple[dict[str, Any] | None, list[dict[str, Any]]]:
+    """Return (usage event or None, tool activity events) for one JSONL line."""
+    try:
+        obj = json.loads(line)
+    except json.JSONDecodeError:
+        return None, []
+    if not isinstance(obj, dict):
+        return None, []
+    return _usage(obj), _activities(obj)
+
+
+def parse_line(line: str) -> dict[str, Any] | None:
+    return parse_record(line)[0]
+
+
+def files(root: Path) -> Iterator[Path]:
+    if root.exists():
+        yield from root.glob("projects/**/*.jsonl")