mancube/loregraph repository overview

⁠loregraph (mancube/loregraph)

A single static Rust binary that turns the chat transcripts your AI coding agents already write to disk into a persistent, provenance-anchored memory knowledge graph of your decisions and the code they shaped.

loregraph reads on-disk agent transcripts (Claude Code JSONL, Codex CLI rollouts, aider's .aider.chat.history.md), fuses them with your repo + git history, and builds a graph of Decision and Implementation nodes — every value node linked by hard provenance edges back to the exact session_id and repo commit. Browse it on a pan/zoom canvas, query it headless so an agent self-recalls instead of re-asking the model, or route the query by the kind of question it is (0.2.0).

• Image: mancube/loregraph — static musl binary on distroless/static, runs as nonroot (uid 65532), no shell, no package manager.
• Arch: linux/amd64, linux/arm64 · Binary inside: /usr/local/bin/lore (entrypoint) · Exposes: 7700 (the serve canvas/API)
• Build: the default feature set plus mcp — still pure Rust, zero Python/C/ML/network, still a fully-static musl binary on distroless. The embedded canvas SPA is baked in (no Node). neural / byo-llm / systemone / index-hnsw stay source-only (each pulls something the image deliberately doesn't: model weights, or reqwest for a network call) — build from source with the matching --features if you want them. Everything below that doesn't say otherwise works in this image as shipped.
• Source / full docs: github.com/lucheeseng827/loregraph⁠ · Apache-2.0

⁠What's new in 0.2.0

Nothing below changes lore ask's default behaviour, the on-disk graph format, or what the default build depends on — every addition is additive and opt-in. See the CHANGELOG⁠ for the full detail, including the safety argument for each.

• Intent-routed recall. lore ask --intent <kind> (or set LORE_INTENT_ROUTING=1 to classify automatically) and lore intent classify/label/train/status bias ranking toward the kind of question being asked (seven intents — decision, code lookup, timeline, …) instead of one fixed ranking for every query shape. The classifier has three tiers: a locally-trained onboard head (pure Rust, trains on your own labelled queries in milliseconds, works in this image), a cue heuristic (always available, the floor that can't fail), and an optional external System-1 judgment model (needs --features systemone, source-only — see below). Nothing is routed unless you ask it to be.
• The System-1 judgment seam, --features systemone (source builds only: it pulls reqwest, which this image deliberately doesn't ship). One client reaches a whole family of typed-judgment servers over POST /v1/systemone — the hosted Jev service and self-hostable servers (openjev, von, or any other wire-compatible one via LORE_SYSTEMONE_ENDPOINT) — so a regulated/air-gapped shop can run its own judgment model with no vendor call at all.
• The portable bundle. lore export writes a graph to one file; lore import merges it — an upsert, not a byte-level copy, so two people's graphs join cleanly and importing the same bundle twice changes nothing. --dry-run previews what would land before it does. Works in this image.

⁠Where it fits

loregraph is the memory tier beside your coding agent: it reads the chat transcripts the agent already writes, fuses them with the repo + git history into a provenance-anchored graph, and hands back citable answers the agent feeds into its next prompt. It owns the transcript → graph → recall hop and nothing else — no model calls, no daemon in the loop, no network, by default.

   SOURCES               LOREGRAPH            THE GRAPH          RECALL / OUTPUT
   (on disk, read-only)  (this image)         (redb store)       (feeds next turn)

 ┌──────────────┐
 │ Agent        │  Claude Code / Codex ─┐
 │ transcripts  │  / aider JSONL        │
 └──────────────┘                       │     ┌─────────────┐    ┌───────────────┐
 ┌──────────────┐                       │     │ Decision /  │    │ ask → answer  │
 │ Repo         │  git spans + commits ─┼──▶  │ Implement.  │──▶ │  + session_id │
 │ (worktree)   │                       │     │ nodes+edges │    │  + commit+file│
 └──────────────┘      ┌─────────────┐  │     │ +provenance │    └───────────────┘
 ┌──────────────┐  ──▶ │  loregraph  │ ◀┘     │ + HNSW vec  │    ┌───────────────┐
 │ git commits  │      │ index·recall│        │ (redb+WAL)  │──▶ │ serve → canvas│
 └──────────────┘      └──────┬──────┘        └─────────────┘    │  + JSON API   │
                              │                                  └───────────────┘
                              ├─▶ intent-routed ranking (onboard head, pure Rust)
                              └─▶ secrets redacted on ingest · zero network calls

• Upstream — the transcripts your agents already write (Claude Code / Codex / aider) plus the repo and its git history. loregraph reads them read-only; it does not call the model or reach the network.
• loregraph — index fuses turns + code + commits into a graph of Decision/Implementation nodes, each anchored to a session_id and the contemporaneous commit; recall queries it (graph + HNSW vectors), optionally routed by intent.
• Downstream — ask returns a citable answer (decision + session + file + commit) the agent feeds into its next prompt instead of re-asking the model; serve exposes the same graph as a pan/zoom canvas + JSON API on 7700; export/import moves the graph itself to another machine.

⁠Tags

Pin a version in production: mancube/loregraph:v0.2.0.

⁠Quick start

The binary is the entrypoint, so the docker args are just lore subcommands (index / serve / ask / intent / export / import / doctor / version). Mount your data dir, transcripts, and repo as volumes — loregraph reads them read-only and writes only its graph.

docker run --rm mancube/loregraph:v0.2.0 version

1. Build the graph — point it at the transcripts your agents already wrote + your repo, and a persistent data dir:

docker run --rm \
  -v "$HOME/.claude/projects:/sessions:ro" \
  -v "$PWD:/repo:ro" \
  -v "$PWD/.lore:/data" \
  mancube/loregraph:v0.2.0 \
  index --sessions /sessions --repo /repo --data-dir /data

2. Browse it — the embedded canvas + JSON API. Bind 0.0.0.0 inside the container (the default 127.0.0.1 isn't reachable from the host):

docker run --rm -p 7700:7700 \
  -v "$PWD/.lore:/data" \
  mancube/loregraph:v0.2.0 \
  serve --addr 0.0.0.0:7700 --data-dir /data
# open http://127.0.0.1:7700/

3. Ask it — headless recall with citable provenance:

docker run --rm \
  -v "$PWD/.lore:/data" \
  mancube/loregraph:v0.2.0 \
  ask "what did we decide about retries?" --data-dir /data
# add --json for a machine-readable RecallResult, or --intent decision to route it

⁠Commands

index defaults: --source claude_code, --data-dir .lore. Add --dry-run to parse + report without writing.

⁠What's inside the graph

• Value nodes — Decision / Implementation, each anchored to a session_id and the contemporaneous repo commit (so you can answer who decided what, when, and which code it shaped).
• Provenance edges — DecidedIn, Implements, Touches (chat turn ↔ file/span), ChangedBy (commit), Supersedes (an explicit "… instead of X …" supersession).
• Durable store — redb + a crash-safe write-ahead log; re-running index is a content-addressed, idempotent upsert. export/import moves the same graph between machines without touching the store's own on-disk format.

⁠Air-gap friendly

The default build (this image) makes zero network calls — it only reads the local files you mount. It runs disconnected, on a laptop, in a locked-down CI runner, or on an air-gapped host. distroless/static + nonroot keeps the attack surface to just the binary. Intent routing's onboard head trains and predicts locally with no exception to that; only the optional external System-1 tier (source builds, --features systemone) reaches a network, and only when you configure LORE_SYSTEMONE_ENDPOINT/LORE_SYSTEMONE_API_KEY — unset, it is off.

⁠License

Apache-2.0. The name loregraph (binary lore) is a working title.