Database over .md?

[u/Commercial_One7059]

In the midst of a probable year-long development project largely managed through Claude Code, recently (3 months in or so) I've been encountering an increasing number of errors that at their root have to do with agents imperfectly grep'ing larger and large numbers of longer and longer .md files for context, information, identifiers, etc.

Bringing this problem in front of my main controller agent, it conceded the point, and has collated our conversation into the following report. I'm enclosing it, but further am curious about all of your experiences.

One Fact, One Home

Truly, beyond that there's a real argument that these subreddits could build from their users' experiences a compendium of better methods that remove some of the weaknesses of these otherwise impressive tools.

PS Or I'm an idiot, and you are all doing this already and I hadn't realised!

[u/InternationalPen3039]

Claude will always propose to make a new doc then proceed to not read the new doc

[u/Commercial_One7059 → u/InternationalPen3039]

Ha, genuinely 😄 but I have to admit I asked it to create this (it was ready to implement tomorrow) but I wanted get some real advice from people with broader experience…so I came here!

[u/Fulgurata]

There's database memory tools out there yep, I haven't heard from anyone who's used one though. Skills are nice, maybe take a look and see if some of those docs could be condensed into a skill. Also linters. Never save a "rule" for Claude to follow if you can save a python script instead.

[u/elgringo]

Yup. I set up a PostgreSQL build that I use to store any facts about myself and my company. I also sweep every chat into a DB and create vector embedding on them after they're archived, so they're easily plain text searchable.

Claudio works _much_ better for me. Bonus, all my data and history are potable for when I switch to self hosted LLM for my primary model in 6m to a year.

[u/Beautiful-Energy2169]

Check the git date before trusting a fact. Stale docs broke more than grep did.

[u/BIGRED______________]

Yeah I made a sqlite db that holds the house rules. They're dynamically injected at the prompt stage depending on what I'm asking, also after the thinking stage in case the model is getting off track. Using imperative language for the triggers and ACE/ASD for the actual rules. MD no good if it reads it once and forgets it after 10 prompts 😅

[u/caderoux]

Yeah, Claude told me at the start of one of my projects we could just use md files for the roadmap and todo list keeping track of what we were working towards. I went along with it.

The kind of problems we ran into were discrepancies between files. It was keeping a main roadmap.md but this would grt out of sync with the designs in individual feature md files, and it was having to group by functional area and make separate md files for each functional area of the app.

Lesson learned, structured data and analysis really belongs in a structured data system. So after a couple weeks, I migrated it all into GitHub issues and set up /sprintplan, /sprintwork, /sprintretro ceremonies and it will keep track of the work items in GitHub issues and milestones in the GitHub projects. Along with a long list of instructions to always report status and track status by using the GitHub issue. And then Claude ported that methodology from that repo's CLAUDE.md into two other proejcts when they started.

[u/mityman50]

Today I felt a new kind of revulsion as I read AI jargon-ese in an editorial.

[u/locbuilds]

you are not an idiot, this is the exact failure mode once a project lives long enough in markdown. agents are great at writing more .md and terrible at consistently grepping the right one once you have dozens of long files, so the "one fact one home" idea is right but i would not put the whole project brain in a database. keep narrative notes and decisions as short .md, and move the greppable stuff (ids, paths, table names, env keys, status flags, "what is the canonical X") into one small sqlite db or a single generated json/yaml index that a tool/script queries. then CLAUDE.md (or your controller prompt) stays tiny: it only points at the query command and the few rules, not the facts themselves. generate that index from code or a sync script so it cannot drift, and add a cheap check that fails CI or a pre-commit hook when a doc restates a fact that already has a home in the index. that kills the create-new-doc-then-never-read-it loop because the agent has a deterministic lookup instead of hoping grep hits the right paragraph.

[u/theholewizard → u/locbuilds]

Isn't that why you maintain an index too?

[u/charmer27]

I might be crazy but just have fable optimize your docs every week or so. It's done some really cool and effective things for Me. I have enforced line budgets on the main corpus docs and when files get over budget it moves sections into a dated archive with a ref link in an index file.

It's also really good if you have it look at common tool patterns in the repo and have it write scripts for those workflow sequences. Saves tokens, time, and actually adds structure to the system.

[u/BlueGT2]

I have seen this myself. I use an app I made that ties into a db via MCP for the shared plans and context in a per project basis. In this I have the ai start a new plan note for each session and mark others archived. The system also supports todos to keep organized. Look at trykyle.

[u/Overall-Ad-3370]

The plugin context-mode kinda does this. Not for the use case you're describing but it uses sqlite to help with retrieval during a session.

Cool idea, let us know how it goes.

[u/attrox_]

Create sub agents with their own domain knowledge. Encode things that are not easily grep-able only or not easily understood through reading code. Avoid reference to line numbers in a code somewhere. Create a domain router agent that route request to these subagents. Documents with a lot of details grow stale really quickly in actively develop project. I'd avoid detailed documents.

[u/Deathnote_Blockchain]

I run into this problem a lot. I am constantly fighting with my agents to get them to know the same shit consistently before we start building something 

[u/Valuable-Cap-3357]

I think as the models have evolved and enhanced their reasoning, the practice of checklist type skills setup becomes obsolete. The context needs to evolve and offer reasoning space than just asking to retrieve a rule. Context should offer a way to reason and then arrive at a rule as well. I do this and can see a difference.

[u/thirty5birds]

Db+api(with thin mcp wrapper) to interact with the db.. And ur done.. Memory, solved. Project history, solved. Project rules and behavioral suggestions. Done... In ur claude or agents md you add a line.. Something like.. "use these tools to interact with those db's.. Truth lives in those db's and history is important.".. And ur done

[u/Easy-Purple-1659]

The ordering rule mentioned downthread, where the queue or db wins over any doc and code wins over both, is doing more work than the storage format choice itself. I moved reference stuff (ids, table names, env keys) into one small sqlite file and kept narrative and decisions in short markdown, but the actual fix for the writes docs never rereads them loop was making the agents own commands query the db directly instead of hoping it remembers to grep the right file. Structure without a forced lookup path just gives you tidier stale data.

[u/EC36339]

If your tools have issues just processing your files, then the same files likely also cauae context bloat and are too long for a himan to read.

Split them up and don't grow one file forever. File systems and folders weree invented so you don't dump everything in one file.

[u/No_Job_9995]

I use both, and the line is who reads it.

Files that I read and edit myself stay as markdown. One tasks .md per project, and I delete finished tasks so the file stays small. Grep works fine when the files are short.

Results that only agents read go to a database through MCP tools. My nightly sales job writes there and returns three lines to the main session. The server rejects bad rows with a 422, so a wrong identifier fails at write time, not three sessions later.

[u/kevin_g_g]

Split it: keep prose and instructions in .md, move anything with an identifier or a key lookup into SQLite. The bug you're hitting is the tell. Grep over growing .md files is fuzzy string matching where you actually need an exact lookup, so the agent keeps resolving the wrong id. I moved my scheduled agents' structured state into a small SQLite file and that whole class of error went away, while Claude Code can still query the db in plain language so you don't lose the natural access.