TECHDEV · Open-source tool

memgraph

Last month a team reversed a queue decision and nobody could say why the first design was picked, what evidence it rested on, or who had signed off on the replacement. The old design was still half-wired in as a fallback, quietly depending on the thing that had just been replaced. They found out in production. Vector RAG remembers text. It does not remember decisions — what was chosen, what it rested on, what contradicted it, and what replaced it. memgraph is a tiny local graph for exactly that: every decision, fact and constraint is a node with a source, linked by what supports, contradicts, supersedes or depends on what.

View on GitHub →Read the article →

Node.js 18+ · Zero dependencies · MIT

What it does

One zero-dependency Node.js CLI. No network, no server, no embeddings. The store is a single JSON file you can commit next to your code.

memgraph init
memgraph add --type decision --title "Use Postgres LISTEN/NOTIFY for the queue" --source "ADR-014"
memgraph add --type fact --title "NOTIFY payloads cap at 8000 bytes" --source "Postgres docs"
memgraph link m-002 m-001 --relation contradicts
memgraph add --type decision --title "Switch the queue to Redis Streams" --source "ADR-019"
memgraph supersede m-001 m-003 --reason "payload cap makes NOTIFY the wrong tool"

Commands copied exactly from the memgraph README ("What it does"). Three questions it answers, fast:

Question	Command
Why did we decide this?	`memgraph why m-003` — source, supporters, contradictions, supersession
Is anything stale or contradictory?	`memgraph check` — unresolved contradictions, live nodes resting on superseded ones, dependency loops, sourceless claims
What do we believe?	`memgraph list` — every node, with superseded ones marked

Try it now

# 1. Clone
git clone https://github.com/techdevfun/memgraph.git
cd memgraph

# 2. No dependencies to install (Node.js 18+). Optional: link the command
npm link   # makes `memgraph` available everywhere

# 3. Start a graph for your own project
memgraph init
memgraph add --type decision --title "Use Postgres for the queue" --source "ADR-014"
memgraph why m-001

Commands copied exactly from the memgraph README ("Try it in 3 steps").

The repo ships a small team graph — a queue decision, the fact that killed it, its replacement, and one leftover fallback still depending on the dead design. Run sh examples/run-demo.sh, then memgraph check: it reports exactly two problems — the fallback reader depends on a superseded decision, and one open question has no source. The contradiction between the payload-cap fact and the old decision is not flagged: the old decision was superseded, so that contradiction is resolved history, not a live conflict.

More commands

# Record evidence and constraints, not just decisions
memgraph add --type fact --title "Peak depth hit 40k jobs" --source "metrics 2026-10-12"
memgraph add --type constraint --title "Queue must survive a broker restart" --source "SLO doc"

# Link them: supports | contradicts | supersedes | depends-on
memgraph link m-001 m-002 --relation supports

# Machine-readable output for scripts and CI
memgraph why m-003 --json
memgraph check --json
memgraph list --type decision --json

Commands copied exactly from the memgraph README ("More commands").

CI gate

memgraph check exits 1 when it finds an error, so it works as a CI gate on a decisions/ folder: a PR that introduces a contradiction, or keeps depending on a superseded decision, fails before it merges.

memgraph check   # exit 1 when it finds an error — run it in CI over a decisions/ folder

Behavior from the memgraph README ("CI gate"), not a copied snippet.

What this is NOT — and where rivals beat us

memgraph does not judge whether a source is true. As the README puts it: a graph is only as good as what you record. memgraph cannot tell you whether a source is true — it tells you where every claim came from and whether the graph still holds together. A decision with no source is a rumor with formatting; that is why check flags it.
Its lane is decision provenance, and that lane only. Vector RAG systems remember text, not decisions — they complement memgraph rather than replace it. Static ADRs in markdown record decisions but are not queryable and have no CI gate; memgraph makes the same records answerable.
When a decision changes, supersede it — do not delete it. Deleting history is how teams end up re-litigating the same choice every six months.

Source + README on GitHub → · Report an issue → · ask@techdev.fun

Limits

A graph is only as good as what you record: an unrecorded decision is invisible to check, and memgraph cannot verify that a recorded source is true.
The README roadmap is not shipped yet: memgraph blame <file> (which decisions touch a file or ADR), time-travel (memgraph at <date>), Mermaid/Graphviz export for ADRs and reviews, and --stale <days> warnings for decisions whose sources are old.
The store is a single local JSON file — there is no multi-user server, no embeddings, and no network sync. That is the design, not a missing feature, but know it before you adopt it.

License

MIT — see LICENSE in the repository.

Have a say

Vote for this tool, suggest a feature, or discuss it with other operators on the community board.