omni-memory-agent 0.1.0__py3-none-any.whl

omni_memory/__init__.py

@@ -0,0 +1,6 @@
+"""OmniMemory — the memory & context layer for coding agents.
+
+Local-first, branch-aware, git-anchored, enforced.
+"""
+
+__version__ = "0.1.0"

omni_memory/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

omni_memory/artifacts.py

@@ -0,0 +1,57 @@
+"""AI-written doc artifacts — api-map.md and linkup.md.
+
+Modeled on the hand-written work/docs kb: an endpoint→service→repo API map and a
+master cross-reference (Mermaid dependency graph + controller/service/repo maps +
+Kafka contracts + shared DBs/code). These regenerate from the live codebase so
+they never drift.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import context, llm
+from .store import Store
+
+APIMAP_PROMPT = """\
+You are OmniMemory generating `api-map.md` for this repository. Output ONLY
+GitHub-flavored Markdown (no preamble). Structure:
+- A short header: base path / auth headers if evident.
+- One section per controller/route group, each with a table:
+  | Method | Path | Request (DTO/params) | Flow: Controller -> Service -> Repository/downstream |
+Be specific: real controller/service/repo class names, real paths, real DTOs,
+real downstreams (DB, Kafka topic, external API). Note Kafka publishes as
+`-> Kafka <topic>`. If a detail is inferred, append `(inferred)`. Base it strictly
+on the code below — do not invent endpoints.
+"""
+
+LINKUP_PROMPT = """\
+You are OmniMemory generating `linkup.md`, the master cross-reference. Output ONLY
+Markdown. Include, in order:
+1. `## Dependency graph` — a Mermaid ```mermaid graph LR``` of repos/services/DBs/
+   queues and how they call each other (REST, Kafka topics, shared DB).
+2. `## Controller -> Service -> Repository` — a table of the main call chains.
+3. `## Event contracts` — Kafka topics with producer(s) and consumer(s).
+4. `## Shared data & code` — shared DBs/collections and shared utility classes.
+Use real names from the code below. Mark inferred items `(inferred)`. No preamble.
+"""
+
+
+def _generate(root: Path, prompt: str) -> str:
+    ctx = context.gather(root)
+    return llm.complete(prompt, ctx).strip()
+
+
+def generate_apimap(store: Store, root: Path) -> Path:
+    out = store.dir / "api-map.md"
+    out.write_text(_generate(root, APIMAP_PROMPT) + "\n")
+    return out
+
+
+def generate_linkup(store: Store, root: Path) -> Path:
+    out = store.dir / "linkup.md"
+    out.write_text(_generate(root, LINKUP_PROMPT) + "\n")
+    return out
+
+
+def generate_all(store: Store, root: Path) -> list[Path]:
+    return [generate_apimap(store, root), generate_linkup(store, root)]

omni_memory/branch.py

@@ -0,0 +1,46 @@
+"""Branch-aware memory: sync git topology into the store, resolve scope."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from . import gitmeta
+from .store import Store
+
+
+def sync_git(store: Store, root: Path) -> dict:
+    """Pull the current git topology into the store. Returns the snapshot."""
+    snap = gitmeta.snapshot(root)
+    for b in snap["branches"]:
+        store.upsert_branch(**b)
+    for c in snap["commits"]:
+        store.upsert_commit(c["sha"], c["branch"], c["author"], c["date"],
+                            c["message"], c["files"])
+    store.set_meta("default_branch", snap["default"])
+    from . import staleness
+    staleness.recompute(store, root)
+    return snap
+
+
+def scope(store: Store, root: Path) -> tuple[str, Optional[str]]:
+    """(current_branch, base_branch|None) honoring the branch-aware toggle.
+
+    branch-aware ON  → memory for current branch + its base.
+    branch-aware OFF → all branches (base returned as None, current as '*').
+    """
+    if not store.get_meta("branch_aware", True):
+        return "*", None
+    cur = gitmeta.current_branch(root)
+    base = store.get_meta("default_branch") or gitmeta.default_branch(root)
+    return cur, (base if base != cur else None)
+
+
+def on_branch_change(store: Store, root: Path) -> None:
+    """Re-sync topology; flip merged branches' memories to 'merged' status."""
+    snap = sync_git(store, root)
+    for b in snap["branches"]:
+        if b["status"] == "merged":
+            store.db.execute(
+                "UPDATE memory SET status='merged' "
+                "WHERE branch=? AND status='active'", (b["name"],))
+    store.db.commit()

omni_memory/cleanup.py

@@ -0,0 +1,80 @@
+"""Extraction-noise filter — drop junk before it becomes a memory.
+
+An LLM (or the doc/heuristic scanner) happily emits aspirational prose, headings,
+and doc boilerplate that pollute the graph and the inject block. A *durable*
+project memory names something concrete — a file, symbol, path, endpoint, table,
+CamelCase type, or quoted term. Generic prose with no such anchor is noise.
+
+Applied in `remember_many` for every capture path. Filtering is source-aware:
+  - ALL sources    → length bounds + structural (markdown/heading/question) reject
+  - doc/heuristic  → additionally require a concrete anchor (these scanners are
+                     the noisy ones; the AI extractor is trusted for prose).
+"""
+from __future__ import annotations
+
+import re
+
+_MIN_CHARS = 12
+_MAX_CHARS = 280
+_PROSE_WORDS = 8  # a label with >= this many words reads like prose, not a name
+
+# Sources whose output is untrusted prose and must carry a concrete anchor.
+_STRICT_SOURCES = {"doc", "heuristic"}
+
+# A memory is "anchored" if it points at something concrete. Any of:
+_PATH = re.compile(r"[\w-]+/[\w./-]+")                 # src/foo/bar.py
+_DOTTED = re.compile(r"\b\w+\.\w+")                    # module.func, Foo.bar
+_SNAKE = re.compile(r"\b[a-z0-9]+_[a-z0-9_]+\b")       # snake_case
+_CAMEL = re.compile(r"\b[a-z]+[A-Z]\w+\b")             # camelCase
+_TYPE = re.compile(r"\b[A-Z][a-z0-9]+[A-Z]\w+\b")     # CamelCase / PascalCase
+_ALLCAPS = re.compile(r"\b[A-Z]{2,}\b")               # KAFKA, HTTP, DB, API
+_ENDPOINT = re.compile(r"(/api/|\b(GET|POST|PUT|PATCH|DELETE)\b|:\d{2,5}\b)")
+_QUOTED = re.compile(r"[\"'`][^\"'`]{2,}[\"'`]")       # "quoted" term
+# A capitalized proper noun that is NOT at the start of the sentence.
+_MIDCAP = re.compile(r"\S\s+[A-Z][a-zA-Z0-9]{2,}")
+
+_ANCHORS = (_PATH, _DOTTED, _SNAKE, _CAMEL, _TYPE, _ALLCAPS, _ENDPOINT, _QUOTED,
+            _MIDCAP)
+
+# Boilerplate / doc-scaffolding fragments that are never durable facts.
+_BOILERPLATE = re.compile(
+    r"^(see |for more|e\.?g\.?|i\.?e\.?|note:|todo:?$|tbd|n/a|coming soon"
+    r"|as follows|for example|in this|this (section|doc|file|guide))",
+    re.I,
+)
+
+
+def _has_anchor(text: str) -> bool:
+    return any(rx.search(text) for rx in _ANCHORS)
+
+
+def is_noise(text: str, files=None, symbols=None, source: str = "session") -> bool:
+    """True if this candidate memory should be dropped as extraction noise."""
+    t = (text or "").strip()
+    if len(t) < _MIN_CHARS or len(t) > _MAX_CHARS:
+        return True
+    # structural markdown / doc scaffolding
+    if t[0] in "#>|=" or t.startswith(("```", "---", "* ", "- ")) and len(t.split()) < 3:
+        return True
+    if t.endswith("?"):                       # questions aren't durable facts
+        return True
+    if _BOILERPLATE.match(t):
+        return True
+    if source not in _STRICT_SOURCES:
+        return False                          # trust AI/manual/session prose
+    # strict path: doc/heuristic prose must name something concrete
+    if files or symbols:
+        return False
+    return not _has_anchor(t)
+
+
+def filter_items(items: list[dict], source: str = "session") -> tuple[list[dict], int]:
+    """Return (kept_items, dropped_count) after removing extraction noise."""
+    kept, dropped = [], 0
+    for it in items:
+        text = (it.get("text") or "").strip()
+        if is_noise(text, it.get("files"), it.get("symbols"), source):
+            dropped += 1
+            continue
+        kept.append(it)
+    return kept, dropped

omni_memory/cli.py

@@ -0,0 +1,341 @@
+"""`omni-memory` / `/omni-memory` command dispatch."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from . import __version__, branch as branchmod, digest, gitmeta, graphbuild, inject
+from . import session_memory as sm
+from .store import Store, find_project_root
+
+
+def _store():
+    root = find_project_root()
+    return Store(root), root
+
+
+def cmd_status(args):
+    s, root = _store()
+    branchmod.sync_git(s, root)
+    c = s.counts()
+    on = s.get_meta("enabled", True)
+    ba = s.get_meta("branch_aware", True)
+    cur = gitmeta.current_branch(root)
+    from . import llm
+    ai = llm.provider() or "none (set GEMINI_API_KEY)"
+    print(f"OmniMemory {__version__}  ·  project: {root.name}")
+    print(f"  layer: {'ON' if on else 'OFF'}   branch-aware: {'ON' if ba else 'OFF'}   AI: {ai}")
+    stale = s.db.execute(
+        "SELECT COUNT(*) n FROM memory WHERE status='active' AND stale=1").fetchone()["n"]
+    stale_note = f"   ⚠ {stale} stale (run: omni-memory check)" if stale else ""
+    print(f"  branch: {cur}   memories: {c.get('active',0)} active, "
+          f"{c.get('merged',0)} merged, {c.get('superseded',0)} superseded")
+    print(f"  store: {s.dir}{stale_note}")
+    return 0
+
+
+def cmd_toggle(args):
+    s, _ = _store()
+    s.set_meta("enabled", args.cmd == "on")
+    print(f"OmniMemory {'enabled' if args.cmd == 'on' else 'disabled'}.")
+    return 0
+
+
+def cmd_branch_aware(args):
+    s, _ = _store()
+    new = not s.get_meta("branch_aware", True)
+    s.set_meta("branch_aware", new)
+    print(f"branch-aware: {'ON' if new else 'OFF'}")
+    return 0
+
+
+def cmd_remember(args):
+    s, root = _store()
+    m = sm.remember(s, root, " ".join(args.text), kind=args.kind, source="manual")
+    digest.write_digest(s)
+    print(f"[+] remembered [{m.id}] ({m.kind}, branch {m.branch}): {m.text}")
+    return 0
+
+
+def cmd_capture(args):
+    """Ingest the agent's extraction JSON (stdin) → memories."""
+    s, root = _store()
+    raw = sys.stdin.read()
+    n = sm.capture_from_json(s, root, raw, source="session")
+    digest.write_digest(s)
+    print(f"[+] captured {n} mem  (branch {gitmeta.current_branch(root)}); digest updated")
+    return 0
+
+
+def cmd_digest(args):
+    s, _ = _store()
+    out = digest.write_digest(s)
+    print(f"[+] knowledge base → {out}")
+    return 0
+
+
+def cmd_build(args):
+    """One-time bootstrap: AI-written facts from the repo + docs + graph."""
+    from . import context, llm
+    s, root = _store()
+    print(f"[*] building OmniMemory for {root.name} …")
+    branchmod.sync_git(s, root)
+    g = graphbuild.build_graph(s, root)
+    (s.dir / "graph.json").write_text(json.dumps(g, indent=2))
+
+    ai_added = 0
+    use_ai = llm.available() and not args.no_ai
+    if use_ai:
+        print(f"[*] AI pass via {llm.provider()} — reading the codebase …")
+        try:
+            ctx = context.gather(root)
+            items = llm.extract_memories(sm.BUILD_PROMPT, ctx)
+            ai_added = sm.remember_many(s, root, items, source="ai-build")
+            print(f"[+] AI wrote {ai_added} facts from the codebase")
+            from . import artifacts
+            for p in artifacts.generate_all(s, root):
+                print(f"[+] artifact → {p}")
+        except Exception as e:  # noqa: BLE001
+            print(f"[!] AI pass failed ({e}); falling back to docs.")
+            use_ai = False
+
+    doc_added, scanned = (0, 0)
+    if not args.no_docs:
+        doc_added, scanned = sm.ingest_docs(s, root)
+    digest.write_digest(s)
+
+    print(f"[+] graph: {len(g['nodes'])} nodes  ·  AI facts: {ai_added}  ·  "
+          f"docs: {doc_added} from {scanned} file(s)")
+    print(f"[+] knowledge base → {s.dir / 'MEMORY.md'}")
+    if not use_ai and not args.no_ai:
+        print("\n[i] No model key set → only heuristic/doc facts. For real AI facts:")
+        print("    export GEMINI_API_KEY=...   (then re-run: omni-memory build)")
+    return 0
+
+
+def cmd_prompt(args):
+    print(sm.BUILD_PROMPT if args.which == "build" else sm.EXTRACTION_PROMPT)
+    return 0
+
+
+def cmd_artifact(args):
+    """Generate the AI-written docs (api-map / linkup)."""
+    from . import artifacts, llm
+    if not llm.available():
+        print("[i] needs a model key. export GEMINI_API_KEY=... then retry.")
+        return 1
+    s, root = _store()
+    which = args.which
+    print(f"[*] generating {which} via {llm.provider()} …")
+    try:
+        if which in ("apimap", "all"):
+            print(f"[+] {artifacts.generate_apimap(s, root)}")
+        if which in ("linkup", "all"):
+            print(f"[+] {artifacts.generate_linkup(s, root)}")
+    except Exception as e:  # noqa: BLE001
+        print(f"[!] failed: {e}")
+        return 1
+    return 0
+
+
+def cmd_inject(args):
+    s, root = _store()
+    if not s.get_meta("enabled", True):
+        return 0
+    block = inject.build_block(s, root, query=" ".join(args.query or []),
+                               files=args.file or None)
+    if block:
+        print(block)
+    return 0
+
+
+def cmd_recall(args):
+    s, root = _store()
+    cur, base = branchmod.scope(s, root)
+    mems = s.memories(branch=None if cur == "*" else cur, base=base,
+                      query=" ".join(args.query), limit=30)
+    if not mems:
+        print("not in memory.")
+        return 0
+    for m in mems:
+        where = ("  · " + ", ".join(m["files"][:3])) if m["files"] else ""
+        stale = " ⚠STALE" if m.get("stale") else ""
+        print(f"[{m['id']}] {m['kind']} ({m['branch']}){stale}: {m['text']}{where}")
+    return 0
+
+
+def cmd_branches(args):
+    s, root = _store()
+    branchmod.sync_git(s, root)
+    for b in s.branches():
+        star = "*" if b["name"] == gitmeta.current_branch(root) else " "
+        merged = f" → merged into {b['into_branch']}" if b["status"] == "merged" else ""
+        who = f"  by {b['creator']}" if b.get("creator") else ""
+        print(f"{star} {b['name']:24} {b['status']}{merged}{who}")
+    return 0
+
+
+def cmd_check(args):
+    """Re-anchor memories against git: flag any whose files changed since they
+    were written as ⚠ stale (they keep their content — re-verify, don't trust)."""
+    from . import staleness
+    s, root = _store()
+    r = staleness.recompute(s, root)
+    print(f"[+] checked {r['checked']} anchored memory · "
+          f"{r['stale']} stale · {r['cleared']} cleared")
+    if r["stale"]:
+        rows = s.db.execute(
+            "SELECT id, kind, text FROM memory "
+            "WHERE status='active' AND stale=1 ORDER BY stale_since DESC LIMIT 20"
+        ).fetchall()
+        for row in rows:
+            print(f"    ⚠ [{row['id']}] {row['kind']}: {row['text'][:80]}")
+    return 0
+
+
+def cmd_forget(args):
+    s, _ = _store()
+    ok = s.forget(args.id)
+    print("forgotten." if ok else "no such memory.")
+    return 0
+
+
+def cmd_map(args):
+    s, root = _store()
+    branchmod.sync_git(s, root)
+    g = graphbuild.build_graph(s, root)
+    out = s.dir / "graph.json"
+    out.write_text(json.dumps(g, indent=2))
+    print(f"[+] graph: {len(g['nodes'])} nodes, {len(g['edges'])} edges → {out}")
+    print("    (next: augment with a tree-sitter AST code graph)")
+    return 0
+
+
+def _read_transcript(path):
+    """Claude Code transcript is JSONL; flatten to 'role: text' for extraction."""
+    from pathlib import Path
+    if not path or not Path(path).exists():
+        return ""
+    out = []
+    for line in Path(path).read_text(errors="ignore").splitlines():
+        try:
+            obj = json.loads(line)
+        except Exception:  # noqa: BLE001
+            continue
+        msg = obj.get("message") or obj
+        role = msg.get("role") or obj.get("type", "")
+        content = msg.get("content", "")
+        if isinstance(content, list):
+            content = " ".join(b.get("text", "") for b in content
+                               if isinstance(b, dict) and b.get("type") == "text")
+        if isinstance(content, str) and content.strip():
+            out.append(f"{role}: {content.strip()}")
+    return "\n".join(out)[-140_000:]
+
+
+def cmd_hook(args):
+    """Claude Code hook entrypoint (reads the event JSON on stdin)."""
+    try:
+        data = json.load(sys.stdin)
+    except Exception:  # noqa: BLE001
+        data = {}
+    s, root = _store()
+    if not s.get_meta("enabled", True):
+        return 0
+    if args.event == "inject":                 # UserPromptSubmit → add memory to context
+        block = inject.build_block(s, root, query=data.get("prompt", ""))
+        if block:
+            print(block)                        # stdout is added to the prompt context
+        return 0
+    if args.event == "capture":                # SessionEnd/Stop → extract + store
+        text = _read_transcript(data.get("transcript_path"))
+        if text:
+            n = sm.capture_from_json(s, root, text, source="session")
+            digest.write_digest(s)
+            print(f"omni-memory: captured {n} memories", file=sys.stderr)
+        return 0
+    return 0
+
+
+def cmd_key(args):
+    """Store an API key securely (~/.omni-memory/credentials.json, chmod 600)."""
+    import getpass
+    import json as _json
+    import os as _os
+    from . import llm
+    env = {"gemini": "GEMINI_API_KEY", "anthropic": "ANTHROPIC_API_KEY",
+           "openai": "OPENAI_API_KEY"}[args.provider]
+    val = getpass.getpass(f"Paste {args.provider} API key (hidden): ").strip()
+    if not val:
+        print("nothing entered.")
+        return 1
+    llm.CREDS.parent.mkdir(parents=True, exist_ok=True)
+    creds = {}
+    if llm.CREDS.exists():
+        try:
+            creds = _json.loads(llm.CREDS.read_text())
+        except Exception:  # noqa: BLE001
+            creds = {}
+    creds[env] = val
+    llm.CREDS.write_text(_json.dumps(creds, indent=2))
+    _os.chmod(llm.CREDS, 0o600)
+    print(f"[+] saved {args.provider} key → {llm.CREDS} (chmod 600, gitignored)")
+    return 0
+
+
+def cmd_ui(args):
+    from . import serve
+    return serve.run_ui(port=args.port)
+
+
+def cmd_install(args):
+    from . import install
+    return install.install(platform=args.platform)
+
+
+def main(argv=None):
+    import argparse
+    p = argparse.ArgumentParser(prog="omni-memory",
+                                description="Memory & context layer for coding agents.")
+    p.add_argument("--version", action="version", version=f"omni-memory {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    sub.add_parser("status")
+    sub.add_parser("on"); sub.add_parser("off")
+    sub.add_parser("branch-aware")
+    r = sub.add_parser("remember"); r.add_argument("--kind", default="fact"); r.add_argument("text", nargs="+")
+    sub.add_parser("capture")
+    ij = sub.add_parser("inject"); ij.add_argument("query", nargs="*"); ij.add_argument("--file", action="append")
+    rc = sub.add_parser("recall"); rc.add_argument("query", nargs="+")
+    sub.add_parser("branches")
+    fg = sub.add_parser("forget"); fg.add_argument("id")
+    sub.add_parser("map")
+    sub.add_parser("check")
+    sub.add_parser("digest")
+    bd = sub.add_parser("build")
+    bd.add_argument("--no-docs", action="store_true")
+    bd.add_argument("--no-ai", action="store_true", help="skip the model pass")
+    pr = sub.add_parser("prompt"); pr.add_argument("which", nargs="?", default="build",
+                                                   choices=["build", "session"])
+    ar = sub.add_parser("artifact"); ar.add_argument("which", nargs="?", default="all",
+                                                     choices=["apimap", "linkup", "all"])
+    hk = sub.add_parser("hook"); hk.add_argument("event", choices=["inject", "capture"])
+    ky = sub.add_parser("key"); ky.add_argument("provider", choices=["gemini", "anthropic", "openai"])
+    ui = sub.add_parser("ui"); ui.add_argument("--port", type=int, default=7777)
+    ins = sub.add_parser("install"); ins.add_argument("--platform", default="claude-code")
+
+    args = p.parse_args(argv)
+    dispatch = {
+        None: cmd_status, "status": cmd_status, "on": cmd_toggle, "off": cmd_toggle,
+        "branch-aware": cmd_branch_aware, "remember": cmd_remember, "capture": cmd_capture,
+        "inject": cmd_inject, "recall": cmd_recall, "branches": cmd_branches,
+        "forget": cmd_forget, "map": cmd_map, "check": cmd_check, "digest": cmd_digest,
+        "build": cmd_build, "prompt": cmd_prompt, "artifact": cmd_artifact,
+        "key": cmd_key, "hook": cmd_hook, "ui": cmd_ui, "install": cmd_install,
+    }
+    return dispatch[args.cmd](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

omni_memory/context.py

@@ -0,0 +1,70 @@
+"""Assemble a compact, high-signal repo snapshot to feed the model on `build`.
+
+Prioritizes the files that reveal architecture: manifests, docs, entrypoints,
+controllers/routes/services/models/config. Truncated to a char budget (a later
+phase adds per-area chunking via the AST code graph for big monorepos).
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+_PRIORITY = (
+    "readme", "package.json", "pom.xml", "build.gradle", "requirements",
+    "pyproject", "go.mod", "cargo.toml", "dockerfile", "docker-compose",
+    "application.yml", "application.properties", ".env.example",
+)
+_DIR_HINTS = ("controller", "route", "service", "handler", "model", "entity",
+              "repository", "schema", "config", "kafka", "consumer", "producer",
+              "api", "endpoint", "main", "app", "index")
+_CODE_EXT = (".py", ".ts", ".js", ".java", ".go", ".rb", ".kt", ".rs", ".md",
+             ".yml", ".yaml", ".sql")
+
+
+def _tracked_files(root: Path) -> list[str]:
+    try:
+        r = subprocess.run(["git", "-C", str(root), "ls-files"],
+                           capture_output=True, text=True, timeout=20)
+        if r.returncode == 0:
+            return [f for f in r.stdout.splitlines() if f]
+    except Exception:  # noqa: BLE001
+        pass
+    return [str(p.relative_to(root)) for p in root.rglob("*")
+            if p.is_file() and ".git" not in p.parts][:5000]
+
+
+def _score(path: str) -> int:
+    low = path.lower()
+    s = 0
+    if any(k in low for k in _PRIORITY):
+        s += 100
+    if low.endswith(".md"):
+        s += 40
+    if any(h in low for h in _DIR_HINTS):
+        s += 20
+    if low.endswith(_CODE_EXT):
+        s += 5
+    s -= low.count("/") * 2          # prefer shallower files
+    return s
+
+
+def gather(root: Path, max_chars: int = 140_000, per_file: int = 6_000) -> str:
+    files = _tracked_files(root)
+    tree = "\n".join(files[:1000])
+    parts = [f"# REPO: {root.name}\n# FILE TREE ({len(files)} files)\n{tree}\n"]
+    budget = max_chars - len(parts[0])
+    for f in sorted(files, key=_score, reverse=True):
+        if budget <= 0:
+            break
+        if not f.lower().endswith(_CODE_EXT):
+            continue
+        try:
+            text = (root / f).read_text(errors="ignore")[:per_file]
+        except Exception:  # noqa: BLE001
+            continue
+        chunk = f"\n\n# FILE: {f}\n{text}"
+        if len(chunk) > budget:
+            chunk = chunk[:budget]
+        parts.append(chunk)
+        budget -= len(chunk)
+    return "".join(parts)

omni_memory/digest.py

@@ -0,0 +1,62 @@
+"""Digest — render the store into a human-readable MEMORY.md "knowledge base".
+
+This is the persistent artifact: always-loadable docs for the agent (Antigravity
+artifact / Claude Code @-reference) and browsable by humans. Regenerated on every
+capture so it never drifts from the store.
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from .store import Store
+
+DIGEST_NAME = "MEMORY.md"
+# Section order + headings modeled on work/docs README reading-order taxonomy.
+_ORDER = ["decision", "concept", "flow", "event", "endpoint", "db",
+          "component", "gotcha", "assumption", "fact", "todo"]
+_HEADINGS = {
+    "decision": "Architecture & Decisions", "concept": "Concepts / Glossary",
+    "flow": "Flows", "event": "Events (Kafka contracts)",
+    "endpoint": "API map (endpoint → service → repo)", "db": "Database",
+    "component": "Reusable components", "gotcha": "Gotchas / Known issues",
+    "assumption": "Assumptions (verify)", "fact": "Facts", "todo": "TODOs",
+}
+
+
+def write_digest(store: Store) -> Path:
+    mems = store.memories(status="active", limit=2000)
+    by_branch: dict[str, dict[str, list[dict]]] = {}
+    for m in mems:
+        by_branch.setdefault(m["branch"], {}).setdefault(m["kind"], []).append(m)
+
+    lines = [
+        "# Project Memory (OmniMemory)",
+        "",
+        f"_Auto-generated {time.strftime('%Y-%m-%d %H:%M')} · {len(mems)} active "
+        "memories · do not edit by hand; use `omni-memory remember/forget`._",
+        "",
+        "> Agents: treat this as verified project truth. Cite `[id]`s you use. "
+        "If something isn't here or in the code, say \"not in memory\" — don't invent.",
+        "",
+    ]
+    default = store.get_meta("default_branch", "main")
+    for branch in sorted(by_branch, key=lambda b: (b != default, b)):
+        merged = store.db.execute(
+            "SELECT status FROM branches WHERE name=?", (branch,)).fetchone()
+        tag = f" _(merged)_" if merged and merged["status"] == "merged" else ""
+        lines.append(f"## `{branch}`{tag}")
+        for kind in _ORDER:
+            items = by_branch[branch].get(kind)
+            if not items:
+                continue
+            lines.append(f"\n### {_HEADINGS.get(kind, kind.title())}")
+            for m in items:
+                where = f"  — `{'`, `'.join(m['files'][:3])}`" if m["files"] else ""
+                flag = " _(inferred)_" if m.get("source") == "inferred" else ""
+                lines.append(f"- {m['text']}{flag}  `[{m['id']}]`{where}")
+        lines.append("")
+    text = "\n".join(lines)
+    out = store.dir / DIGEST_NAME
+    out.write_text(text)
+    return out