Giving a coding agent a markdown memory is the easy part. Keeping that memory from going stale as the code moves on is the hard part, and it's the part most "memory" tools quietly skip. Here's the whole system, one slide at a time.
On anything bigger than a weekend project, a coding agent loses the plot. It starts every session cold, re-derives decisions you already made, and (the worst one) confidently acts on guidance that stopped being true three commits ago. A memory that never forgets the wrong things isn't memory. It's a liability.
The unit of knowledge is one markdown file with structured frontmatter. The frontmatter
is the machine-read contract. The body is the human detail. No database, no server, just diffable files in your
repo that get reviewed in the same PR as the code. The related_files list binds a concept to the code
it concerns, so the moment you touch a bound file, its concepts surface on their own.
--- id: TD-014 title: Cursor-based pagination for the public API type: technical-decision status: active tags: [api, pagination, performance] related_files: [ src/api/list-handler.ts ] description: Offset broke on deep page loads; cursors are stable. ---
The type isn't a free-text tag. It's a closed, opinionated set, because a known type is what lets the system treat a decision differently from a process or a lesson. Code is the first domain, not the only one.
This is the heart of it. Every concept carries a status, and that status is what keeps the graph fresh instead of letting it rot. When a newer decision lands, the old one gets superseded. When something just stops being true, it gets deprecated. Neither one is deleted. Both are surfaced as stale, so the agent is never silently handed dead guidance.
In June 2026 Google open-sourced the Open Knowledge Format, a draft spec for typed, resource-bound, markdown-native knowledge. It validates the model CLEAR has been running since 2025. The honest read is three layers. OKF specifies a format. CKS adds the lifecycle. CLEAR is the engine that lives it.
The graph gives you the structure to traverse. The lifecycle keeps it true. Building the software is what maintains both.
CLEAR installs via npm or the QBall-Inc plugin marketplace. Pick one, restart your session, and run the guided setup.
# Option A — npm claude /plugin install npm:@qball-inc/clear # Option B — marketplace claude /plugin marketplace add QBall-Inc/plugins-market claude /plugin install clear@qball-inc
# restart, then /cf-init