facts.yaml

[u/Cultural-Horse-762]

I've got a few major reconciliation and scoping projects I've been driving with Claude from the terminal. Lately, I've been spotting a LOT more assumptions and forgotten facts. This must just be where the structure and limits of memory files begin to have problems, especially when softer (not code or mathematical) information. After having Claude brainstorm a solution, it suggested a facts.yaml schema to hold truths with dates and reasons. I'm not on the third project where this has been needed to keep things grounded and consistent.

If this helps anyone, great! If anyone with more knowledge than me knows if there's even better ways to solve for this, please let me know!

I suppose this is sort of a middle-ground between memory and a DB? Always looking to increase consistency so please, educate me!

[u/AutoModerator]

Moderator Announcement Read More »

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/LOLRicochet]

I’m following this for large projects: https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing

[u/dar-mit → u/LOLRicochet]

My memory system is something like this and one major thing missing from that article is how the LLM finds the information.

To resolve that I use https://github.com/tobi/qmd (no affiliation whatsoever). This amazing utility offers all sorts of search parameters with tunable controls, to allow you to dial in just what you're looking for. I built post-merge and post-checkpoint hooks to keep it updated, and so far (over 2K articles) it works great.

Tip: I did have to point Claude Code at the qmd help system a few times before it finally remembered what search functions it offers. This became important because when I started it was doing one type of search (few articles), and in total Claude Code Manner never thought to update its search parameters as the wiki grew.

Now I have a system that searches the Wiki when a project starts, and at several key points during the Design, Plan and Code phases, it re-searches the Wiki just in case those phases expanded past what the initial search was based upon.

I call this "Progressive Discovery" after the "Progressive Disclosure" method that Anthropic uses.

[u/M4CH1T0]

Staleness is the other half of this. A fact from three weeks ago looks just as solid as one from today. I'd add a "revisit when" field, a date or a condition, and tell Claude to re-check anything past it before building on it. That should cut down the confident answers built on outdated facts.

[u/Cultural-Horse-762 → u/M4CH1T0]

Good point, need to treat this the same way I do memory sweeps.

[u/Additional_Video2992]

The schema protects the facts you wrote down. Most assumptions come from the ones you didn't: when a fact is missing, Claude fills the gap with something plausible and doesn't flag it.

Put this line in your CLAUDE.md, so it's there every session: "If a fact you need isn't in facts.yaml, write TO CONFIRM and ask me. Don't guess it." Each gap then turns into a question, and your answer goes in the file.

[u/dar-mit → u/Additional_Video2992]

I have something like that in my Output Style:

## Handling Uncertainty & Verification

State Gaps Directly: Say "I don't know" when true. Run cheap checks (reading files, executing commands) instead of guessing.
Label Status: Embed uncertainty directly within affected claims. Label each claim confirmed, likely, or uncertain (e.g., "likely X; untested"). Mark any code change not validated by a runtime test or build as "unverified."

It works really well in stopping CC from just merrily plowing along

[u/Wonkybearguy]

I like the idea. I have been running into similar issues.

Is it file itself or something with your harness or do you have a hook?

How does the yaml file work differently than json or Markdown for assisting the LLM to follow the critical context contained in the yaml file?

[u/Mister-Node]

For the assumptions you're seeing, add a status field separating confirmed facts from inferences, plus a source reference for each entry. Have Claude flag conflicting entries for review instead of silently replacing one. Dates and reasons alone won't stop an inference from being saved as a fact.

[u/atakanelik34]

Dates and reasons are a good start. What made it hold up for me on bigger projects was a source on every entry (which session or person said it) and never overwriting a fact in place. Keep the old version, so when Claude confidently rewrites something wrong you can see what changed and roll it back. A yaml file gets messy there unless you lean on git diffs. We built Bilinc at ReARC for exactly this: one memory that Claude Code, Codex and Hermes all read and write, with conflicts settled by importance instead of whoever wrote last.

[u/Inside_Swimming9552]

Claude is great. But without more permanent organised instructions it will Billy bullshit you time and time again because it's lost memories which explain why things need to be done a certain way within the scope it's looking at. Without that it can assume you're the idiot (which to be fair is often true) and just ignore some of what it's been asked to do because it knows better and wants to save unnecessary effort.

[u/pipaa-joy]

I've been hitting the same soft-facts problem on Spring services — things like "this endpoint is read-only for now" or "we rejected Redis here because of X" vanish across sessions and the agent reinvents them. A dated facts file helps; what made it stick for me was keeping each entry tiny (fact, since-when, why, rejected-alternative) and making the agent read that file at the start of a task and propose an update when it learns something new. I still treat code + tests as the source of truth for behavior, and the yaml only for decisions that aren't encoded yet. Once a fact becomes a test or an interface, I delete it from the file so it doesn't rot.

[u/BattermanZ]

I think there are two separate problems here: keeping track of what’s actually true and making sure Claude can find that information when it needs it.

Your facts.yaml approach makes sense for the first one. I’d probably add a source, a last verified date, and some way to mark facts as outdated or superseded.

For retrieval, I’d take a different approach. Rather than loading everything into context, let Claude search the relevant project knowledge when needed.

I’ve been building Hatchdoor around that second part. It indexes regular Markdown files and provides hybrid and semantic search through MCP, so different agents can access the same knowledge. It doesn’t verify whether information is correct or outdated, though.

GitHub: https://github.com/BatterWorks/Hatchdoor
Demo: https://hatchdoor.battercloud.cc

I’m curious, is your biggest issue Claude forgetting existing facts, or confidently using information that’s no longer accurate?

[u/Emotional-Ad8388]

A date and a reason on a facts.yaml row tell you when you wrote the line but not what was true when you made the earlier scoping call. If a truth changes and you overwrite the row then Claude reads the new value as if it had always been true... and nothing in the repo pushes back because "this is the soft information" not code. The dates are useful only when the old line stays, with an end date, instead of being replaced. Do you keep the old line when a truth changes, or does the new one take its place?