omni-memory-agent 0.1.0__tar.gz

omni_memory_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhinav Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omni_memory_agent-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md PLAN.md
+recursive-include omni_memory/static *.html
+recursive-include omni_memory/skills *

omni_memory_agent-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: omni-memory-agent
+Version: 0.1.0
+Summary: Persistent, branch-aware, git-anchored memory & context layer for coding agents.
+Author: Abhinav Singh
+License: MIT
+Keywords: ai,memory,coding-agent,knowledge-graph,claude-code,mcp
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: graph
+Requires-Dist: networkx>=3.0; extra == "graph"
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.110; extra == "serve"
+Requires-Dist: uvicorn>=0.29; extra == "serve"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# ◇ OmniMemory
+
+**The memory & context layer for coding agents** — persistent, branch-aware,
+git-anchored, fully local. Your AI stops forgetting between chats and stops
+hallucinating architecture it never verified.
+
+> Plugs into **Claude Code** and **Antigravity** (more IDEs coming). Toggle with
+> `/omni-memory`. Browse everything in a minimalist local dashboard.
+
+## Install
+
+**Option A — Claude Code plugin (no pip needed).** The zero-dependency engine
+rides along inside the plugin, so this is all it takes:
+
+```
+/plugin marketplace add SinghAbhinav04/Omni-Memory
+/plugin install omni-memory@singhabhinav
+```
+
+That wires the skill + the capture/inject hooks automatically. Just work — memory
+injects on every prompt and updates itself when a session ends.
+
+**Option B — pip (gives you the `omni-memory` CLI everywhere).**
+
+```bash
+pip install omni-memory-agent      # or, from a clone: python -m pip install -e .
+omni-memory install                # wire it into Claude Code (the CLI is `omni-memory`)
+omni-memory build                  # one-time: seed memory from the repo (optional)
+omni-memory status
+```
+
+The core is **zero-dependency** (Python stdlib + SQLite) and runs with **no API
+key**. Set `GEMINI_API_KEY` (or Anthropic/OpenAI) only if you want the AI-written
+build pass and artifacts.
+
+## What it does
+- **Remembers** decisions, facts, request/data flows, gotchas — automatically at
+  the end of each session, and on demand.
+- **Branch-aware** — memory is scoped to your git branch; tracks branch creator,
+  timeline, and merge status. Merged branches roll into the base.
+- **Enforced** — injects a *VERIFIED PROJECT MEMORY* block into prompts and makes
+  the agent cite what it used, or admit "not in memory" instead of inventing.
+- **Relevant** — an IDF-tiered ranker surfaces the few memories that actually
+  match your prompt + the files in play, instead of dumping everything.
+- **Self-checking** — `omni-memory check` re-anchors memories against git and
+  flags any whose files changed since they were written as ⚠ stale.
+- **Clean** — an extraction-noise filter keeps aspirational prose and doc
+  boilerplate out of the store.
+- **Graph + dashboard** — `omni-memory ui` opens a local UI: browsable memory
+  docs, the knowledge graph, and the repo/branch graph.
+
+## Commands
+```
+omni-memory status | on | off | branch-aware
+omni-memory build          # one-time: AI-written facts from the repo + docs
+omni-memory ui             # local dashboard (graph + memory docs + repo graph)
+omni-memory map            # (re)build the knowledge graph
+omni-memory check          # re-anchor vs git; flag stale memories
+omni-memory recall <q>     # query memory instead of grepping
+omni-memory branches       # git topology + per-branch memory
+omni-memory remember "…" [--kind decision|fact|flow|gotcha|todo|…]
+omni-memory forget <id>
+omni-memory digest         # (re)write the MEMORY.md knowledge base
+omni-memory artifact [apimap|linkup|all]   # AI-written cross-reference docs
+omni-memory key <gemini|anthropic|openai>  # store a model key securely (chmod 600)
+omni-memory install [--platform claude-code|antigravity]
+```
+
+## How it works
+```
+CAPTURE (session + git) → STORE (SQLite, branch-tagged) → RANK + INJECT + ENFORCE
+       → CHECK (staleness vs git) → VISUALIZE (dashboard)
+```
+Capture fires from deterministic harness events (`UserPromptSubmit` → inject,
+`SessionEnd` → capture) — never left to the agent's goodwill. Local-first, no
+cloud, no paid data. See [`PLAN.md`](PLAN.md) for the full architecture and roadmap.
+
+## Status
+Core is in: store · git provenance · branch-aware scoping · capture/inject/enforce
+· IDF relevance ranker · staleness anchoring · noise filter · `map` · dashboard
+(knowledge graph + repo/branch graph). Roadmap: Antigravity via MCP, tree-sitter
+AST code graph, runtime request-flow capture. See `PLAN.md`.
+
+## License
+MIT © 2026 Abhinav Singh

omni_memory_agent-0.1.0/PLAN.md

@@ -0,0 +1,290 @@
+# OmniMemory — the memory & context layer for coding agents
+
+> **One line:** the memory layer that actually remembers your *architecture* —
+> branch-aware, flow-aware, git-anchored, fully local, across every chat and IDE.
+
+Your AI coding agent forgets everything between chats, re-greps the same files,
+and hallucinates architecture it never verified. OmniMemory is a persistent,
+self-updating, graph-backed memory that plugs into Claude Code and Antigravity
+(more IDEs later), keeps learning as you work, and **forces the agent to use
+verified project memory instead of guessing** — with a minimalist local
+dashboard to browse it all.
+
+---
+
+## 0. Positioning & why it wins
+
+Most memory tools do *one* of these well; OmniMemory owns the intersection —
+and adds the pieces none of them cover:
+
+| Capability | OmniMemory |
+|---|---|
+| Local code knowledge graph (AST) | ✅ |
+| Evolving conversational memory | ✅ (local, zero-cloud) |
+| Contradiction handling + forgetting | ✅ |
+| Multi-IDE skill install + MCP | ✅ |
+| **Branch-aware memory + git provenance** | ✅ ⭐ |
+| **Staleness anchoring (memory re-verified against code changes)** | ✅ ⭐ |
+| **Runtime request-flow capture (real params/returns)** | ✅ ⭐ |
+| **Enforced usage (anti-hallucination)** | ✅ ⭐ |
+| **Local dashboard (graph + readable memory docs + repo graph)** | ✅ ⭐ |
+| Fully local / free | ✅ |
+
+The ⭐ rows + the local dashboard are the reason-to-exist and the star magnet.
+Viral demo: *"switch to my feature branch → it already knows what changed there,
+who started it, and whether it merged."*
+
+---
+
+## 1. Module map
+
+**Core (built, zero-dep):**
+- `store.py` — SQLite store + schema, contradiction/supersede, staleness columns
+- `session_memory.py` — SessionEnd capture (transcript+diff → memories)
+- `cleanup.py` — extraction-noise filter (anchored facts in, doc prose out)
+- `rank.py` — IDF-tiered relevance ranker for retrieval
+- `staleness.py` — flag memories whose files changed since they were written
+- `inject.py` — prompt injection + enforcement (cite [id]s or "not in memory")
+- `branch.py` / `gitmeta.py` — branch-aware scoping + git provenance
+- `graphbuild.py` — knowledge graph from memory + git topology
+- `digest.py` / `artifacts.py` — MEMORY.md + AI-written api-map / linkup
+- `llm.py` / `context.py` — optional model layer (key-optional) + repo snapshot
+- `serve.py` + `static/` — local dashboard (graph · memory docs · repo graph)
+- `install.py` — multi-IDE hook/skill wiring
+
+**Planned:** `runtime.py` (runtime flow capture), a tree-sitter AST code graph
+under `graph/`, and an MCP server face for non–Claude Code agents.
+
+---
+
+## 2. Commands (`/omni-memory …`) — modular, user-friendly
+
+Everything is a toggle/subcommand; nothing is forced on.
+
+```
+/omni-memory                 status + turn the layer on/off for this project
+/omni-memory on | off        enable/disable memory injection
+/omni-memory branch-aware    toggle branch-scoped memory (on by default)
+/omni-memory map             (re)build the code/knowledge graph
+/omni-memory ui              launch the local dashboard (browser)
+/omni-memory graph           open the interactive graph view
+/omni-memory recall <q>      query memory instead of grepping
+/omni-memory why <x>         trace/explain a connection between two things
+/omni-memory branches        show the repo git-graph + per-branch memory
+/omni-memory flows           show request/call-flow diagrams
+/omni-memory forget <id>     drop / archive a stale memory
+/omni-memory status          what's remembered, current branch, store size
+/omni-memory install         wire into Claude Code + Antigravity
+```
+
+---
+
+## 3. Architecture — 5 layers (additions only, nothing rebuilt)
+
+```
+ CAPTURE  ──►  STORE  ──►  SERVE  ──►  INJECT+ENFORCE  ──►  VISUALIZE
+ (static +     (SQLite +   (MCP for    (prompt hook +      (local dashboard:
+  chat +       graph,      agent,      citation rules)      graph · docs ·
+  runtime +    branch-      HTTP for                        repo-graph ·
+  git)         tagged)      the UI)                         flows · timeline)
+```
+
+1. **Capture**
+   - *Static:* AST code graph + DB schema introspection + deps + OpenAPI/endpoints
+   - *Conversational:* SessionEnd hook → extract decisions / facts / gotchas / flows
+     from the transcript + diff (uses the agent's own model)
+   - *Runtime (later):* ingest logs / test runs / optional instrumentation → actual
+     params, return shapes, success vs failure paths
+   - *Git:* `gitmeta.py` → branch creator, timeline, base, merge commit/date, status
+2. **Store** — local `.omni-memory/` (SQLite + graph JSON). Every memory tagged
+   `branch`, `kind`, `files[]`, `symbols[]`, `status`, `confidence`, `source`,
+   linked to commit range. Contradiction-check + supersede + forget.
+3. **Serve** — `serve.py` runs **MCP** (for the agent) **+ FastAPI** (for the UI)
+   over the same store. `/omni-memory install` writes the per-platform config.
+4. **Inject + Enforce** — a prompt hook retrieves the relevant memories (current
+   branch ∪ base + files in context + query) and graph subgraph, injects a
+   **"VERIFIED PROJECT MEMORY"** block with rules: *use it, cite the memory IDs
+   you relied on, and if it's not in memory say so — don't invent.* Agent reports
+   used IDs → logged (proves it's using memory; powers the demo + trust).
+5. **Visualize** — minimalist monochrome dashboard (see §6).
+
+---
+
+## 4. Data model (SQLite, local)
+
+```
+memory(id, branch, kind[decision|fact|flow|gotcha|todo|api|db|endpoint],
+       text, files[], symbols[], commit_range, created, updated,
+       status[active|merged|abandoned|superseded], confidence, source,
+       supersedes_id)
+
+branches(name, creator, created_at, base_branch, ahead, behind,
+         status[active|merged|abandoned], merged_at, merge_commit, into_branch)
+
+commits(sha, branch, author, date, message, files[])
+
+flows(id, name, entry, steps_json[success/failure with params+returns], branch)
+
+graph_nodes / graph_edges  (branch-tagged; AST code graph)
+memory_commit_link(memory_id, sha)
+```
+
+---
+
+## 5. Core loop (v1 = continuous memory + enforcement + branch-aware)
+
+1. **Capture** — SessionEnd hook → structured memories tagged with current git
+   branch + touched files; contradiction-check, supersede stale.
+2. **Inject** — prompt hook → relevant memories + subgraph → "VERIFIED PROJECT
+   MEMORY" block with enforcement instructions.
+3. **Branch-aware** — memories filter by branch; git hooks flip `status` on
+   branch-switch / merge (merged rolls into base; abandoned is archived).
+   `/omni-memory branch-aware` toggles branch-scoping vs global.
+4. **Enforce** — agent cites used memory IDs; `querylog` records usage.
+
+---
+
+## 6. Frontend — minimalist local dashboard (monochrome, offline)
+
+Launched by `/omni-memory ui` → FastAPI serves a **bundled** Vite+React SPA on
+localhost (works offline; ships pre-built in the wheel).
+
+**Views:**
+- **Graph** — interactive connected-knowledge graph (d3 force-directed)
+- **Memory** — every stored memory as browsable, searchable "docs"; filter by
+  branch / kind / file; click to read full entry + linked files/symbols/commits
+- **Repo Graph** — the git DAG (`@gitgraph/js` or d3): `main` trunk + feature
+  branches, merge points + dates + **branch creator**; click a commit/branch →
+  the memories attached to it (git history *is* the memory index)
+- **Flows** — request/call-flow diagrams (Mermaid + runtime later)
+- **Timeline** — memory growing over time ("it's alive")
+
+**API:** `/api/memories` (list/search/filter) · `/api/memory/:id` · `/api/graph`
+· `/api/branches` · `/api/commits` · `/api/flows`. MCP = agent face, HTTP = UI face.
+
+---
+
+## 7. IDE integration (scope: Claude Code + Antigravity)
+
+- **Claude Code:** a `/omni-memory` skill + hooks in settings.json
+  (SessionEnd → capture; UserPromptSubmit/PreToolUse → inject+enforce) + MCP
+  server for recall tools.
+- **Antigravity:** via the MCP server (same `serve.py`) + its rules/memories
+  mechanism.
+- `/omni-memory install` writes both via per-platform config writers.
+- Extensible to Codex / OpenCode / Gemini CLI / VS Code via the same MCP + skill
+  pattern.
+
+---
+
+## 7a. Knowledge-base format — the north star (modeled on real usage)
+
+OmniMemory's job is to **auto-generate and maintain** the kind of AI knowledge
+base a senior dev builds by hand. Reference: `Documents/work/docs` (a real
+multi-repo BFHL platform kb). We mirror its proven shape:
+
+- **Indexed with a reading order** — `MEMORY.md` opens with architecture →
+  concepts → flows → events → api-map → db → components, then running notes.
+- **Kinds mapped to that taxonomy:** `decision · concept · flow · event (kafka
+  contract) · endpoint (controller→service→repo+params) · db · component ·
+  gotcha/known-issue · assumption (verify) · todo · fact`.
+- **Confidence markers** — `EXTRACTED / INFERRED / ASSUMPTION` on every fact.
+- **Two killer auto-generated artifacts (P1/P2, from the AST graph + runtime):**
+  - **api-map** — every endpoint → controller → service → repo/downstream with
+    DTOs/params/headers (replaces hand-written `api-map.md`).
+  - **linkup** — the master cross-reference: Mermaid repo-dependency graph,
+    controller→service→repo maps, Kafka producer/consumer contracts, shared
+    DBs/code (replaces hand-written `linkup.md`).
+- **Multi-repo aware** — one memory/graph spanning sibling repos, because real
+  systems are many repos.
+- **Mermaid** for dependency/flow diagrams in the dashboard + digest.
+
+## 7b. Autonomy & persistence — why this beats other memory tools
+
+The failure of every memory tool is that **updating** the memory is left to the
+agent's goodwill — and agents forget. OmniMemory's rule: **never rely on the
+agent to remember to update.** Capture fires from deterministic *harness events*,
+and retrieval is always-on.
+
+**Claude Code (hooks = harness-run, not agent-run):**
+- `UserPromptSubmit` → `omni-memory inject` (always injects verified memory).
+- `SessionEnd` / `Stop` → `omni-memory capture` (extracts from transcript+diff
+  via a small model, deterministically — no agent decision needed).
+- `PostToolUse(Edit|Write)` → mark graph stale / incremental re-map.
+- The skill + `MEMORY.md` digest are always available for @-reference.
+
+**Antigravity (artifacts = always-in-context knowledge):**
+- Write the `MEMORY.md` digest as a persistent **artifact** so it's always
+  loaded into context (no re-fetch).
+- Register OmniMemory as an **MCP server** for deep recall + capture tools.
+- Capture on task-complete events where available; else a cadence + the
+  staleness nudge below.
+
+**Staleness watchdog (the "keep reminding to update" fix):** the store tracks
+`last_capture` + commits since. If stale, the injected block **prepends a
+directive** ("⚠ memory N commits stale — capturing now") and the hook runs
+capture. Automation is the fix; the nudge is only the fallback. Result: the
+knowledge base updates itself as you work, across branches, without you or the
+agent having to remember.
+
+## 8. Repo structure
+
+```
+omni-memory/
+  omni_memory/
+    cli.py            # /omni-memory dispatch
+    store.py          # SQLite store + schema
+    branch.py         # branch-aware memory logic
+    gitmeta.py        # git provenance (creator, timeline, merges)
+    session_memory.py # SessionEnd capture (transcript+diff → memories)
+    inject.py         # prompt injection + enforcement
+    runtime.py        # runtime flow capture (P2)
+    serve.py          # MCP + FastAPI
+    api.py            # HTTP endpoints for the UI
+    install.py        # multi-IDE wiring
+    graph/            # AST code graph (extract/build/cluster/export/callflow)
+    static/           # bundled dashboard (single-file HTML)
+  web/                # optional richer dashboard build
+  skills/omni-memory/ # the skill package (SKILL.md + refs)
+  LICENSE(MIT)  README.md  PLAN.md  pyproject.toml
+```
+
+---
+
+## 9. Phases
+
+- **P0 — core** — store + branch model + git metadata + Claude Code capture /
+  inject / enforce hooks + `/omni-memory map`. Demoable: persistent,
+  branch-aware, enforced memory in Claude Code.
+- **P0.5 — minimal dashboard** — FastAPI + Graph & Memory-docs views (the demo UI).
+- **P1 — branch-aware, full** — git provenance + **Repo Graph** view + Antigravity (MCP).
+- **P2 — runtime flow capture** — endpoint→DB→Kafka→params/returns, success vs failure.
+- **P3 — polish** — contradiction/forgetting tuning, Timeline/Flows views, more
+  IDEs, perf, tests. **Launch:** Show HN / Trendshift, demo GIF.
+
+---
+
+## 10. Enhancements / roadmap (post-v1)
+
+- **Contradiction & decay tuning** — confidence scoring, auto-expire stale memory.
+- **Team mode** — optional shared memory (git-synced `.omni-memory/` or a light server).
+- **PR/issue ingestion** — pull decisions from PR descriptions & review threads.
+- **"Why did we…" answers** — trace a decision to its commit + chat origin.
+- **Onboarding mode** — new dev asks the repo questions, gets guided tours.
+- **Language coverage** — extend the tree-sitter AST extractors.
+- **Runtime adapters** — OpenTelemetry / log-format plugins for flow capture.
+- **Secrets safety** — redact params/returns; never store credentials.
+- **Export** — GraphML / Obsidian vault of the whole memory.
+- **Eval** — benchmark recall/enforcement (LongMemEval/LoCoMo style) for credibility.
+
+---
+
+## 11. Principles
+
+- **Local-first, free.** No mandatory cloud, no paid data. Your code never leaves.
+- **Deterministic where possible.** Code graph via AST (no LLM); LLM only for the
+  semantic/conversational layer.
+- **Never guess.** Enforcement makes the agent cite memory or admit it doesn't know.
+- **Minimalist.** Clean monochrome UI, modular toggles, one-command install.
+- **Zero-dependency core.** The whole memory engine runs on the Python stdlib;
+  extras (graph analysis, richer serving) are strictly optional.

omni_memory_agent-0.1.0/README.md

@@ -0,0 +1,85 @@
+# ◇ OmniMemory
+
+**The memory & context layer for coding agents** — persistent, branch-aware,
+git-anchored, fully local. Your AI stops forgetting between chats and stops
+hallucinating architecture it never verified.
+
+> Plugs into **Claude Code** and **Antigravity** (more IDEs coming). Toggle with
+> `/omni-memory`. Browse everything in a minimalist local dashboard.
+
+## Install
+
+**Option A — Claude Code plugin (no pip needed).** The zero-dependency engine
+rides along inside the plugin, so this is all it takes:
+
+```
+/plugin marketplace add SinghAbhinav04/Omni-Memory
+/plugin install omni-memory@singhabhinav
+```
+
+That wires the skill + the capture/inject hooks automatically. Just work — memory
+injects on every prompt and updates itself when a session ends.
+
+**Option B — pip (gives you the `omni-memory` CLI everywhere).**
+
+```bash
+pip install omni-memory-agent      # or, from a clone: python -m pip install -e .
+omni-memory install                # wire it into Claude Code (the CLI is `omni-memory`)
+omni-memory build                  # one-time: seed memory from the repo (optional)
+omni-memory status
+```
+
+The core is **zero-dependency** (Python stdlib + SQLite) and runs with **no API
+key**. Set `GEMINI_API_KEY` (or Anthropic/OpenAI) only if you want the AI-written
+build pass and artifacts.
+
+## What it does
+- **Remembers** decisions, facts, request/data flows, gotchas — automatically at
+  the end of each session, and on demand.
+- **Branch-aware** — memory is scoped to your git branch; tracks branch creator,
+  timeline, and merge status. Merged branches roll into the base.
+- **Enforced** — injects a *VERIFIED PROJECT MEMORY* block into prompts and makes
+  the agent cite what it used, or admit "not in memory" instead of inventing.
+- **Relevant** — an IDF-tiered ranker surfaces the few memories that actually
+  match your prompt + the files in play, instead of dumping everything.
+- **Self-checking** — `omni-memory check` re-anchors memories against git and
+  flags any whose files changed since they were written as ⚠ stale.
+- **Clean** — an extraction-noise filter keeps aspirational prose and doc
+  boilerplate out of the store.
+- **Graph + dashboard** — `omni-memory ui` opens a local UI: browsable memory
+  docs, the knowledge graph, and the repo/branch graph.
+
+## Commands
+```
+omni-memory status | on | off | branch-aware
+omni-memory build          # one-time: AI-written facts from the repo + docs
+omni-memory ui             # local dashboard (graph + memory docs + repo graph)
+omni-memory map            # (re)build the knowledge graph
+omni-memory check          # re-anchor vs git; flag stale memories
+omni-memory recall <q>     # query memory instead of grepping
+omni-memory branches       # git topology + per-branch memory
+omni-memory remember "…" [--kind decision|fact|flow|gotcha|todo|…]
+omni-memory forget <id>
+omni-memory digest         # (re)write the MEMORY.md knowledge base
+omni-memory artifact [apimap|linkup|all]   # AI-written cross-reference docs
+omni-memory key <gemini|anthropic|openai>  # store a model key securely (chmod 600)
+omni-memory install [--platform claude-code|antigravity]
+```
+
+## How it works
+```
+CAPTURE (session + git) → STORE (SQLite, branch-tagged) → RANK + INJECT + ENFORCE
+       → CHECK (staleness vs git) → VISUALIZE (dashboard)
+```
+Capture fires from deterministic harness events (`UserPromptSubmit` → inject,
+`SessionEnd` → capture) — never left to the agent's goodwill. Local-first, no
+cloud, no paid data. See [`PLAN.md`](PLAN.md) for the full architecture and roadmap.
+
+## Status
+Core is in: store · git provenance · branch-aware scoping · capture/inject/enforce
+· IDF relevance ranker · staleness anchoring · noise filter · `map` · dashboard
+(knowledge graph + repo/branch graph). Roadmap: Antigravity via MCP, tree-sitter
+AST code graph, runtime request-flow capture. See `PLAN.md`.
+
+## License
+MIT © 2026 Abhinav Singh

omni_memory_agent-0.1.0/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_agent-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_agent-0.1.0/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_agent-0.1.0/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()