Inspiration

You tell a coding agent "use pnpm in this repo, not npm". Next session it runs npm install again. Instruction files help, but they are flat lists: they can't tell which rule applies to this request, never notice you've said the same thing three times, and quietly pile up rules that contradict each other. Corrections aren't a list. They're connected context.

What it does

ToldOnce turns every correction into a lesson in a Relate graph, linked to the projects, tools and tasks it covers. Before the agent acts, one Cypher query recalls the lessons that connect to what you just asked, and each hit says why it surfaced (tool git, task commit, text 0.81, told 2x).

  • A git lesson follows you into every repo that uses git, through (:Project)-[:USES]->(:Tool), which is fingerprinted from the repo.
  • Project lessons never leak into other projects. Task lessons only fire when the task is in the prompt.
  • Newer rules supersede older ones (history kept). Conflicting rules are surfaced so the agent asks instead of guessing.
  • If you correct something the agent was already told, it's linked as a repeat, not a duplicate. toldonce stats shows exactly what you've had to say twice.

How we built it

  • Python on the embedded relate-db library, one .rl file per user, plus a committed demo store.
  • Recall is a single statement in recall.cypher: EXISTS {} / COUNT {} subqueries, pattern comprehensions, variable-length SUPERSEDES*1.., blended with a Relate full-text SEARCH for hybrid ranking.
  • Integrations: a Claude Code UserPromptSubmit hook that injects a <toldonce> block (and optionally captures corrections automatically), a dependency-free stdio MCP server (recall, learn, supersede, history), and a CLI.
  • A browser demo runs the real engine through @relate/relate-wasm on the exported demo store, using the same recall.cypher file. A test enforces that.

Challenges

Deciding scope semantics: a lesson tied to a tool should reach projects that use that tool, but a lesson tied to one project must never leak. Expressing that as one readable Cypher filter, rather than application code, was the core design work. Repeat detection is lexical (full-text plus token overlap) and doesn't catch every paraphrase yet. Vector search is the next step.

What we learned

Embedded graph queries make agent memory explainable: every recalled rule comes with the path that justified it.

AI disclosure

Built with significant help from Claude (Anthropic) as a coding agent: design, code, tests, demo page and README. All work was done during the contest period.

Built With

Share this project:

Updates

Submission history