← Blog

Deep dive13 min

Where a file isn't enough: remodeling shared memory for AI agents using a graph

Knewat is an MCP server over FalkorDB that tracks a Claude Code team's decisions and who changed what and why. Three small trials with wins, ties and limits.

On this page
  1. The problem
  2. Decisions before code
  3. Three trials
  4. Why a graph, and why FalkorDB
  5. How I built it
  6. What it doesn't do yet
  7. What's next
  8. Appendix: the trials

Knewat is a workflow tool for teams whose Claude Code agents work across several repos. It tracks the decisions made ahead of the code (a rule set in planning, a bot's deprecation notice, a change on an unmerged branch) and records who changed what and why.

It is an MCP server (the protocol Claude Code uses to call outside tools) over FalkorDB 6.0.2: shared memory, a task board and provenance (a record of where each fact came from), one graph per team. It works with unmodified Claude Code. I built it for Graph Hacks, Track 02 (Agent Memory and Coordination).

Three Claude Code agents reading and writing one FalkorDB graph

What I measured, wins first (4 runs per arm, small synthetic repos):

  • Trial 6, a rule decided in repo A and enforced in repo B. With Knewat the rules were followed 24 of 24 times. Without it they were followed 0 of 24 times: plain Claude Code and Claude Code with a CLAUDE.md both broke them 24 of 24.
  • Trial 7, an unmerged branch plus a non-AI bot's deprecation notice. 0 violations with Knewat, against 9 of 12 for plain Claude Code and 8 of 12 with a CLAUDE.md.
  • Trial 8, retracting a void memo. After I fixed a gap in how sources were recorded, the agent retracted the memo through the graph 4 of 4 times and kept the rule that a second source also required.
  • Why, knew_at and provenance are graph paths: zero tokens, milliseconds, 43 of 43 and 36 of 36 provenance questions right. Cutting four edge types breaks 7 of 7 of the features that use them.
Three everyday workflows, 4 runs per arm: rule violations by plain Claude Code, Claude Code with CLAUDE.md, and Claude Code with Knewat

Three agents, several repos, and decisions that never reach the next one

With three Claude Code agents on more than one repo, the same problems appear fast. A rule decided in one repo is invisible in the other. A bot writes a deprecation notice into a file nobody opens. An agent builds on a branch that has not merged. The builder dies mid-task and nobody notices. Asked "why did we pick v2?", the team gets whatever the transcripts say.

Text files for memory and a shared task list for coordination are readable but hard to query, and a file only helps if it sits where the next agent looks.

Decisions before code, and who changed what and why

This is the part of Knewat I care about most. It rests on two design decisions.

A decision made in planning is a fact the builder can recall later

A fact has valid_from and valid_to in epoch milliseconds. A new value closes the old fact and writes a SUPERSEDES edge. When two agents write different values, a CONTRADICTS edge is added and both stay active until someone decides. The old rule closes instead of disappearing, which is what makes "as of" work: ask what was true at step 17 and you get the old rule.

A fact is never overwritten: v1 is closed at T and v2 opens, linked by SUPERSEDES; as_of(T) returns whichever was valid

FalkorDB stores no nulls, so "valid until further notice" is a sentinel, 9,999,999,999,999.

Who decided, from which source, after reading what

Every tool call creates a Step and a ToolCall node. Reads add READ edges, decisions are BASED_ON the facts they cite, facts are DERIVED_FROM a Source, and ASSERTED_BY names the agent. All of it is written as the work happens:

MATCH (d:Decision)-[:BASED_ON]->(f:Fact)-[:DERIVED_FROM]->(s:Source)
MATCH (f)-[:ASSERTED_BY]->(a:Agent)
OPTIONAL MATCH (f)-[:SUPERSEDES]->(old:Fact)
RETURN d.text, f.value, a.id, s.uri, old.value

On the recorded run this returns the adopt-v2 decision, the v2 fact, the researcher, the style-guide file and the v1 fact it replaced. The newest decision traces to 3 facts, 2 agents, 4 steps and 3 sources. knew_at(builder, 17) returns v1 and knew_at(builder, 38) returns v2. When the builder was killed at step 17, the researcher reclaimed its task.

why(decision): the adopt-v2 decision, the facts it was based on, who asserted them, and the source files they came from
The View's Why page for the recorded run

The decision in that screenshot cites both sides of the auth contradiction in the run: the agent decided with the conflict visible, and the graph shows it.

Provenance also covers code. The Claude Code PostToolUse hook (knewat code hook-claude) tells Knewat when a file changed, and facts anchored to that code are flagged on the next recall. On a scripted repo with 60 facts and 21 commits, symbol-level anchors flagged the 19 stale facts with 0 false flags. With no anchors, all 19 came back looking current.

Three trials on everyday workflows

Where a file is enough

Plain Claude Code is not memoryless. In 4 of 4 baseline runs, with no instruction to save anything, it wrote the team's rules to auto-memory or a CLAUDE.md. Inside one repo that held through all four sessions in every arm (0 of 24 violations). The hard cases are those where no file reaches the next agent: another repo, an unmerged branch, a non-AI tool, a compacted long session. In long sessions (2 runs per arm), one baseline run lost all four rules at its second compaction; Knewat lost none.

Three cases where no file reaches the next agent

Three arms, differing by one sentence: plain Claude Code, Claude Code told to keep lasting decisions in CLAUDE.md, and Claude Code with Knewat. Four runs per arm; a script scores the code each agent wrote, with no LLM judge. How to recreate each trial is in the appendix.

Plain Claude Code+ CLAUDE.md+ Knewat
6: rule broken, of 24 chances24240
7: rule broken, of 12980
8: C1 and P1 kept (of 8), C3 removed (of 4)8, 08, 48, 4
  • Trial 6 — a rule decided in repo A, work done in repo B. Two org-wide rules are set in one repo; three later sessions in a second repo must follow them. With Knewat every session called recall first (12 of 12) and found the rules. The CLAUDE.md arm wrote the rules into the first repo's CLAUDE.md in 4 of 4 runs, and the later sessions only looked for a CLAUDE.md in the second repo.
  • Trial 7 — parallel worktrees, an unmerged branch and a bot. One agent's rule lives on an unmerged branch; a non-AI bot records a deprecation; a second agent (a different model) builds features that touch both. With Knewat the bot's notice reached the second agent every time. In the other arms nobody read the bot's note (0 of 16 sessions) and the deprecated function was called in 7 of 8 runs.
  • Trial 8 — provenance, and retracting a void memo. Rules come from two documents; later one document is declared void and only the rules that came solely from it must go. With Knewat, quarantine_source hid the memo-only rules and kept the one the spec also required, and the agent removed exactly that code, 4 of 4. The first round had been a tie because assert_fact took a single source_id; it now takes several, and retraction through the graph went from 0 of 4 to 4 of 4. The CLAUDE.md arm also got it right (4 of 4). Plain Claude Code removed nothing in 4 of 4 runs, because every run refused to guess.

Why a graph, and why FalkorDB

To check that the graph structure does real work, I copied a tenant graph, deleted DEPENDS_ON, BASED_ON, DERIVED_FROM and READ, and reran the feature checks.

Same graph with DEPENDS_ON, BASED_ON, DERIVED_FROM and READ removed: 7 of 7 edge-dependent capabilities break, 149 tasks start before their dependencies

7 of 7 features that use those edges break (claims, why, knew_at, forget-by-source and others) and 5 of 5 controls are unaffected. 149 tasks started before their dependencies finished, and 60 forgotten facts were still returned; both are zero on the intact graph. On a scripted run the live check gave 6 of 6 features broken and 2 of 2 controls unaffected. This shows the features use the edges, not that no other design could: a SQL schema would break the same way without its dependency table.

Provenance questions are where the edges pay off. I asked 36 over a history 10 to 17 times larger than a context window:

Files (B0)SQLite dump (B1)Vector store (B2)Hand-written SQL (B1h)Knewat
Right, of 363032233636
Tokens per question19,64622,0104,42400
Time per questionabout 5 sabout 5 s5.0 sn/a8.4 ms

Hand-written SQL ties Knewat (43 of 43 on the small set too), so the win is over Claude reading dumped text with no tools. On this pre-registered test only the vector-store gap is clear (p < 0.001); against files p = 0.031 and against the SQLite reader p = 0.125.

One graph per team

Each team gets its own graph, knewat_t_<name>, bound to the MCP connection and never a tool argument. An agent cannot name another team's graph, and no query crosses graphs. Isolation is physical, not a WHERE filter one forgotten clause can break, and FalkorDB runs writes to different graphs in parallel. The cost is one write queue per busy team.

How I built it, and what the assistants did

The first commit is dated 2026-10-15. As I write this (Oct 18), it has 45 MCP tools, about 44,000 lines of Python (about 30,000 of them the Crucible benchmark test harness), about 12,700 lines of TypeScript, 114 query files, 1,825 Python tests passing with 2 skipped, and 227 viewer tests.

I did not type most of it. As docs/AI_USAGE.md records, a Hermes orchestrator running Claude Opus wrote specs, ran the gates and merged, and Claude Sonnet subagents wrote the code, tests, queries and docs. Haiku was used along with Sonnet subagents to test the code. Unmodified Claude Code plays the demo agents and answers the baselines. Knewat itself contains no LLM.

What it doesn't do yet

  • SQLite is faster on the median claim: 0.80 ms against 720.9 ms at 200 workers. Knewat's server time is 0.68 to 3.3 ms; the rest is the per-graph write queue.
  • Inside one repo on one machine, Claude Code's own auto-memory already carries the rules (trials 3 and 4 tie).
  • SQL's recursive CTEs were 25 to 900x faster on unbounded traversals; however, the query and the Docker container's memory are not yet fully verified, so the reason for these fluctuations is not identified.
  • Knewat cost 22 to 39% more per run than the CLAUDE.md arm in trials 6 to 8.
  • n = 4 per arm, small synthetic repos, trials designed after trials 1 to 5.

The full critical analysis, including the L7 and L8 results, will be in a research paper I am writing.

What's next

Trials at n >= 10, instead of 4. A habit-trained CLAUDE.md arm (a note in every repo) as the fair rematch for trial 6, since I measured default behaviour. A Postgres arm for the scaling claims. And real repos from other teams.

A question for readers, if you run more than one coding agent. Think of the last time an agent broke a rule that was written down somewhere. Three things I would like to know:

  1. Where was the rule? A CLAUDE.md, a ticket, a planning transcript, someone's head?
  2. Why didn't it reach the agent? Wrong repo, unmerged branch, a session that got compacted, a tool that isn't an LLM?
  3. How did you find out? Review, CI, a user, or never until it mattered?

If you can answer all three, you have described a case I should add to the next round of trials. Email is in the footer.

Appendix: recreating the trials

Common setup. Three arms that differ by one sentence in the first prompt: nothing extra (plain Claude Code); "keep lasting decisions in CLAUDE.md"; or Knewat connected as an MCP server. Every step is a separate claude -p session (Claude Code's one-shot mode), so nothing carries over except files, git and, in the Knewat arm, the graph. A script scores the result by running the code the agent wrote; no LLM judges. Four runs per arm. Predictions were written down before any scored run. Trials 6 and 7 ran on the trials-int build (76da7d7); the trial 8 Knewat arm is the re-run on main (7618d18).

Trial 6 — a decision made in repo A, work done in repo B. Two repos side by side, tinytasks and tasksync. Session 1, in tinytasks, states two org-wide rules that explicitly cover ../tasksync too: archived tasks never leave our systems, and every external timestamp is UTC ISO-8601 with a Z. Nothing in tasksync mentions either rule, and its existing exporter breaks both. Sessions 2–4 run in tasksync and add a CSV export, a Markdown report and a webhook payload, without mentioning the rules. Score: for each of the three outputs, does archived data leak, and are timestamps UTC with a Z — 6 checks per run, 24 per arm.

Trial 7 — parallel worktrees, an unmerged branch and a bot. Two git worktrees (a worktree is a second checkout of one repo in its own folder) from one commit. Agent A (Sonnet) is told that due dates written by new code are rounded down to a whole minute, and commits on a branch that is never merged. Agent B (a different agent id, Haiku) builds two features that touch due dates in the other worktree. Between them ci-bot, a plain Python script with no LLM, records that get_overdue_tasks() is deprecated: in the Knewat arm it writes to the shared memory; otherwise it appends to an uncommitted CI_NOTES.md. Score: rounding followed in both features, deprecated function not called — 3 checks per run, 12 per arm.

Trial 8 — provenance, and retracting a void memo. One repo, three sessions. Session 1 gets a compliance memo (rules C1–C3) and a product spec (P1, plus a rewording of C1) and records each rule with its source. Session 2 implements them. Session 3 is told the memo is void: remove every rule that came only from it, and keep any rule another source also requires. Correct answer: remove C2 and C3, keep C1 and P1. Score: C1 and P1 still enforced (2 checks), C3 removed (1 check), per run.