Inspiration
Agents that work on the same project keep rediscovering the same things. When they do share notes, nobody reviews them, so one wrong note becomes everyone's truth. Code has had an answer to this for years: a change arrives as a pull request and is reviewed before it lands. Shared agent notes often skip that review.
Relate made that step possible. Its Markdown store turns a folder of notes into a graph database: folders are labels, notes are nodes, wikilinks are relationships, and Cypher reads and writes the files. Put that folder in git and the graph gets history, branches and pull requests for free.
Then we found the catch. Git merges text, and a memory graph can be damaged by a merge git calls clean. Two branches each add the same property to one note on different lines. Git merges them without a conflict. The note now has a duplicate key, Relate reads it as empty, and every relationship it had is gone, with no error anywhere. memory-pr is built to catch that, and the other ways a clean text merge can leave a graph wrong.
What it does
memory-pr gives a team of agents one shared memory that is reviewed like code.
- The memory is a Relate graph stored as Markdown in the repository. Facts link to the entity they are about, the agent that asserted them, their source, the fact they replace, and the facts they were derived from.
- Every change an agent makes arrives as a pull request. An agent cannot write to shared memory directly.
- A check reads the pull request as graph facts, not as text. It comments what the change adds, what it contradicts and what the merge would silently destroy, with the path through the graph that proves it. It is a required check, so a bad change cannot be merged.
What the check catches that a text diff and a clean git merge do not:
| What happened | Git says | The graph says |
|---|---|---|
| Two agents record different databases for one service, in two new notes | clean merge | one fact now has two current values |
| An agent replaces a fact that other facts were derived from | clean merge | facts still rest on something no longer true, up to 6 hops away |
| Two branches add the same property to one note | clean merge | the note reads as empty and all its links are gone |
| A fact points to a source nobody wrote down | clean merge | the fact cannot be verified |
Agents use the memory through an MCP server (mempr mcp): recall current facts with their sources, run read-only Cypher, propose or retract a fact on their own branch, and read the review. For something the memory does not know, the answer is "Nothing known. Do not guess", not an empty list to fill in.
The live page runs Relate itself in the browser. Its "Write a memory" section lets you play the agent: fill in a plain form (or click a starter), see the Markdown note it becomes, open a pull request, and watch the same six rules block or pass it; one-click fixes turn a blocked change green, and Merge adds it to the page's memory so your next change is reviewed against it. Nothing leaves the page. It draws the memory and five pull requests on the graph, runs each review rule as Cypher on click, and lets you write to the graph and watch the review change.
Measured result
300 pull requests from simulated agents (5 seeds, 30% carry one of four mistakes), replayed with and without the check. At the end a new agent asks the memory about every service.
| Without the check | With the check | |
|---|---|---|
| Wrong facts in memory at the end | 20 | 1 |
| Contradictions in memory | 24 | 0 |
| Facts resting on a replaced fact | 9 | 0 |
| Notes emptied by a merge git called clean | 3 | 0 |
| Facts with no source | 20 | 0 |
| Questions answered correctly (of 240) | 140 | 160 |
| Questions answered wrongly or with two values | 18 | 1 |
| Correct pull requests blocked by mistake | 0 | 0 |
The one wrong fact left with the check is a true change whose pull request stayed blocked, so the memory kept the older value. One command reproduces the table; it is in the README.
How we built it
- Relate Markdown store as the only database. The git-tracked notes are the data. There is no import step and no second copy.
- Cypher for every read and write: recall, fact writes with
MERGE, and all six review rules, including a variable-lengthDERIVED_FROM*1..6path query for facts resting on a replaced fact and aSUPERSEDEScycle query. - A graph three-way merge. The check loads four versions of the graph with Relate (common ancestor, base branch, pull request, and git's own merge result from
git merge-tree), merges the graphs itself, and compares that with what git produced. A fact neither side removed that is missing after git's merge is reported as dropped. - Relate embedded in Python (
relate-db) inside the CLI, the MCP server and the GitHub Action. - Relate's WebAssembly build in the static demo page, running the same rules on the same data in the browser.
- GitHub Actions for the review comment and required status, and for a scripted agent that opens real pull requests in five scenarios.
- Rules are read from the base branch, so a pull request cannot change the rules it is reviewed with.
Challenges we ran into
- Relate reports a note with a duplicate YAML key as an empty node and raises no error, so the damage is invisible unless you compare graphs. That comparison became the core of the check.
- Relate writes sidecar files into a store it opens. A read-only review must not change the checkout, so every review runs on a temporary copy.
- GitHub holds workflow runs on pull requests opened by the Actions token, so the required check never reported on agent pull requests. The review now also sets a commit status, which GitHub counts.
- A contradiction rule that is too simple blocks legitimate updates. The rule had to understand supersession, so replacing a fact is allowed and stating two current values is not. In the benchmark no correct pull request is blocked.
Accomplishments that we're proud of
- A judge can see the whole thing without installing anything: a real blocked pull request on GitHub, and Relate running in the page.
- The claim is measured: wrong facts in memory fall from 20 to 1 across 300 simulated pull requests, with no correct pull request blocked.
- 60 tests (verified on November 20, 2026), including the clean-merge damage case reproduced end to end with real git branches.
What we learned
Storing a graph as Markdown in git is more than a file format. It gives a graph the review habits teams already have for code. But text tools only see text, so the review has to happen at the graph level, and Cypher is a good language for writing those review rules: each rule is one query whose rows are the findings.
What's next
- Suggested fixes in the review comment as ready-to-commit changes.
- A graph-aware merge driver, so git itself merges the notes correctly instead of only being checked afterwards.
- Rules for trust: weigh facts by the reliability of the agent and source that asserted them.
Setup instructions (for judges)
No install: open https://memory-pr.vercel.app/
For repository maintainers with workflow permissions: Actions > demo-agent > Run workflow opens a new real pull request in one of five scenarios. Judges can inspect the existing blocked and passing pull requests above, or reproduce the agent flow locally using the commands below.
Locally (Python 3.10+, git 2.38+):
git clone https://github.com/himanshu748/memory-pr && cd memory-pr
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest -q
mempr recall payments-api
python demo/agent.py run --scenario contradiction
mempr check --base origin/main --head HEAD
What the project uses
- Relate capabilities: the Markdown vault store, Cypher for all reads and writes including variable-length path queries, the embedded Python library (
relate-db1.2), and the WebAssembly build (@relate/relate-wasm) in the browser. - Third-party tools: PyYAML, the MCP Python SDK, Cytoscape.js (graph drawing in the page), pytest, ruff, the Geist and Geist Mono fonts (self-hosted, SIL Open Font License), GitHub Actions, and Vercel and GitHub Pages for hosting the static page.
- AI tools: built with AI assistance (Devin). The demo agents are scripted and call no model.
- Data: all data is generated and fictional. The demo is a silent screen capture of the application and GitHub; it contains no voice or footage of a person.
Built With
- cypher
- cytoscape.js
- git
- github-actions
- javascript
- markdown
- mcp
- python
- relate
- webassembly