Inspiration

Xiaoyuan 14B is a local-first 14B agent architecture I run on my own machine. It already produced useful answers, but its memory was a flat transcript: a reader could see what it said, not which gate had fired, which scenario it was in, or which hard constraint forced a repair. For an agent that is supposed to be auditable, that is backwards. The interesting part is not the text; it is the chain of decisions behind the text.

Relate by Neo4j made the fix small. It is an embedded graph database: no server, no signup, one .rl file. I could model the transcript as connected facts and ship the database with the repository.

What it does

Xiaoyuan Memory Graph ingests one real local regression run and turns it into a queryable evidence graph:

  • 10 sessions (Q1-Q10)
  • 31 turns
  • 31 post-checks
  • 5 repaired checks
  • 5 issue occurrences
  • 13 scenarios
  • 20 extracted hard-constraint links

A session has turns; each turn points to its scenario and its check; a check can find an issue; a turn can include hard constraints; the session records the model. The graph is not a chat log with extra fields. The relationships are the product: Session -> Turn -> Check -> Issue, plus IN_SCENARIO, INCLUDES, and USED_MODEL.

How it uses Relate

  • Mode: single-file Relate store at data/xiaoyuan_memory.rl.
  • Why: the graph persists between runs, travels with the repo, and a judge can inspect it without starting a service. seed --reset rebuilds it from the JSON transcript when a clean reproduction is wanted.
  • What the graph models: sessions, turns, checks, issues, scenarios, constraints, and the model. Every node keeps provenance, so a query can answer "which repaired turn was in the routing scenario, and which issue triggered the repair?"

Example:

MATCH (s:Session {id: 'Q8'})-[:HAS_TURN]->(t:Turn)-[:CHECKED_BY]->(c:Check)
OPTIONAL MATCH (c)-[:FOUND]->(i:Issue)
RETURN t.id, t.scenario, c.valid, c.repaired, collect(i.text) AS issues
ORDER BY t.index;

The CLI exposes the same graph through seed, stats, ask, trace, sessions, and demo; a small read-only HTTP dashboard renders the sessions and scenario stats from the same .rl file.

How I built it

  1. Started from the real fixture data/ten_question_regression_full.json, produced by a local Xiaoyuan 14B regression run on 2026-11-17 with qwen2.5:14b-instruct-q4_K_M served by Ollama.
  2. Wrote the tests first for the public surface: seed_fixture, recall_session, gate_trace, scenario_stats, and constraints_for_turn. The first run failed because the ingest module did not exist; the final suite is 5/5 passing.
  3. Implemented a Relate-backed store, idempotent MERGE ingest, deterministic constraint extraction, query helpers, a CLI, and a read-only dashboard.
  4. Seeded a fresh store and checked the counts: 10 sessions / 31 turns / 31 checks / 5 repairs / 5 issues / 13 scenarios / 20 constraints.
  5. Cloned the public repo into a clean directory and reran the tests and a fresh seed --reset to prove the repository is reproducible, not just a folder of files.

Challenges

The first challenge was modeling "an issue" without losing occurrence. The same routing-format problem appears in two different turns, so an issue is not a global label; it is an occurrence attached to a specific check. I gave each occurrence its own node ID (turn_id-issue-N) so the graph preserves both the shared text and the separate evidence.

The second was keeping the demo honest. Relate is new, and I only verified the Cypher surface the project actually uses. Scenario statistics are aggregated in Python from rows returned by Cypher rather than relying on unverified collect/CASE behavior. The README states that boundary instead of implying a broader compatibility claim.

The third was reproducibility. A graph file in a repository can easily become an opaque binary. The project therefore commits both the source JSON and the seeded .rl, and seed --reset regenerates the latter. A judge can inspect the store, or rebuild it from the transcript.

What I learned

Connected context changes the question an agent can answer. With a flat transcript, the best question is "what did it say?" With a graph, the question becomes "which gate fired, on which turn, in which scenario, against which constraint, and what was repaired?" That is the difference between memory as storage and memory as an audit trail.

What is real, and what is not

The input, counts, model name, and five repaired turns come from the local regression transcript. All results are local self-evaluation. This is not an official score, ranking, leaderboard entry, or third-party safety certification. The public repository does not include private production source or model weights.

Built With

Share this project:

Updates

Submission history