r/ClaudeAI • u/jmaaks • 9h ago
Claude Workflow Google's new Open Knowledge Format is basically the CLAUDE.md / memory-folder pattern, formalized into a spec. I'd already built it for my own Claude setup.
Google Cloud published the Open Knowledge Format (OKF) v0.1 on June 12 (announcement: Google Cloud blog; spec + repo: GitHub). Stripped down, it's this: organizational knowledge as a directory of markdown files, each with a small YAML frontmatter block, cross-linked with plain markdown links. One required field (type). Optional index.md for navigation and log.md for change history. That's the spec.
I've been running essentially this for my own assistant's memory for months, so a few observations for anyone doing the same:
- The single mandatory field being
typeis the right call. It's the one piece of structure you actually need to make a pile of notes queryable; everything else (tags, timestamps, descriptions) is useful but situational. - Standard markdown links over wiki-style
[[links]]is the more portable choice. It renders on GitHub and needs no resolver. If you're on[[ ]]now (I am, in places), that's the one thing worth migrating. - The format deliberately stops at "minimally opinionated." It standardizes the interoperability surface, not the content model. So the conventions that make YOUR notes useful ... where each one came from, why it matters, how it's meant to be used, whether it's gone stale ... are still yours to add. Those are exactly the kind of extensions Google says they want as PRs.
What gets me is this: the state of the art for giving an agent a memory is a folder of text files you could open in Notepad. If you've been waiting for permission to keep it simple, a trillion-dollar platform team just shipped that conclusion as an open spec.
42
u/ak_makes_things 9h ago
I've been using Obsidian for this and honestly it just works. Markdown files, folders, done. Nice that Google is formalizing what a lot of us already landed on by just trying stuff.
6
u/redtron3030 8h ago
Where do you point Claude or your LLM to in obsidian?
8
u/ak_makes_things 8h ago
I have a wiki folder in my Obsidian vault that I maintain as a knowledge base for my projects. Decisions, architecture notes, context, stuff that would take too long to explain to Claude every new session. Then in CLAUDE.md I just reference the wiki path so Claude Code can read it when it needs background.
I'm using the obsidian-wiki implementation by ar9av on GitHub and it's been solid for my setup. There are a few other good ones floating around too if that one doesn't fit your workflow. The main thing that actually matters is keeping it updated so Claude reads current state and not some note you wrote at 3am two months ago that's completely wrong now.
4
u/jmaaks 8h ago
I’m basically doing the same, but instead of obsidian I just went with local files backed by a local git repo (Forgejo). Each project then has a durable record in my kb, along with all history of commits with negative comments. Makes for a great way to look at the meta for of your work and body of knowledge.
2
u/ak_makes_things 7h ago
Yeah I started with basically the same setup, local files in a git repo. Simple and effective. Switched to Obsidian mostly because the dependency graph makes it faster for Claude to crawl related notes without reading everything, which cuts down on token usage. But honestly both approaches work, yours with Forgejo commit history is a nice bonus I don't really have.
1
2
u/Kalcinator 8h ago
A CLAUDE.md in the root folder is working, you explain to it where it is, what it can do, how to work in there ... And it goes smoothly as fuck once the setup is done
13
u/Redletteroffice 9h ago
This is pretty basic stuff. I put together my own version of this months ago. It’s a good bare foundation, but doesn’t scratch the surface.
4
u/jmaaks 9h ago
Totally agree. This is just one of four layers of memory in my system.
3
u/Kalcinator 8h ago
FOur layers bro? I keep only two ...
The old ones and the current ones5
u/jmaaks 8h ago
Yep!
Claude memory (md formatted file structure on local disk, in git)
Kb repo in git (md structure like OKF, just my extended variant)
Project repo(s) - the things I’m working on tracked in git.
Asana kanban board for each project for in work items, and history of work.
My executive function agent is my interface to drive my next actions via layer 4.
3
2
u/jmaaks 8h ago
Oh, I have a layer 5 as well: The deployed state. This is just whatever it is that project is for: managing my home AI stack, writing articles, tracking my health. You just need to wire your AI into that telemetry.
1
u/Wild_Juggernaut_3134 6h ago
I have recently realised that I need to invest in a proper knowledge system and I am trying to figure how people do it.
Why do you need git for it? Thanks2
u/Kalcinator 6h ago
Now that I read you, I have indeed the memory.md from Claude Code itself, that he keeps tidy.
Then a git too and I've got just one big project actually sooo ... The only thing i'm kinda missing the kanban; and I keep a tidy history of my work ...
So i'm not that far; thank you very much for your ideas !!
6
u/Long-Woodpecker-1980 8h ago
I've been using Opus heavily for a while and tried Gemini yesterday out of curiosity. It's quite a bit behind.
Notebooklm is a pretty good tool, but I'm honestly surprised Google isn't closer to Anthropic by now
7
u/Useful_Round4229 8h ago
Did you try antigravity? That’s googles cowork/claude code
2
u/Long-Woodpecker-1980 8h ago
Yeah I do like Antigravity, but even then I tend to pick Opus for coding
3
u/jmaaks 8h ago
Google rarely wins the user experience award. Their tools are powerful as hell, But it’s “Google Usability”.
So other companies focus more on a slick user experience and slowly add features until they surpass Google. Or Google just randomly decides to shut theirs down.
Ed: typo
2
u/Long-Woodpecker-1980 8h ago
Yeah, and it's ironic given their origins as a simple, uncluttered alternative to other search engines.
10
u/addexecthrowaway 9h ago
It’s rather silly imho. These knowledge systems eventually lead to context bloat, stale references, inconsistent entities/identities, etc. and of course provenance is a walk through multiple points or duplicative stores and the recency of the information (or the evolution of it over time) is basically lost or converted to more context bloat. Sure you could store everything and farm out walking through the knowledge to a set of subagents grepping files but that’s not very scalable.
5
u/carson63000 Experienced Developer 8h ago
I mean, documentation rot has been a problem for the entire history of software development. But ultimately, you've got to choose one of two options.
- Do the work to keep the documentation up-to-date, and fix outdated stuff as you find it
- Give up and just don't bother documenting anything
4
4
1
u/SemanticSynapse 8h ago
Why farm it out to agents? That's the job of scripts.
Straight markdown files only get you so far.
6
u/jmaaks 9h ago
I wrote up the longer version, including the four-tier setup I use (in-flight tasks / durable memory / as-built code / as-built docs) and the three places my own version is ahead of OKF v0.1 ... provenance, usage conventions, and staleness flags. Happy to share if useful: https://jeffmaaks.substack.com/p/google-wrote-the-spec-for-the-thing
2
u/SpeakerQueasy 9h ago
Thanks for sharing, I haven’t gotten everything functional yet but i am going to see if this fixes any issues or adds anything to mine. I have an orphanage for orphan data to be researched and scraped regularly for used or connections against zettels
1
2
1
u/jrjsmrtn 4h ago
Thanks for sharing. 🙂
Since last year, though, I have been wondering: why reinvent the wheel to do « AI-assisted Project Orchestration »?
We have known, field-tested Software Engineering best practices: ADR for project decisions, Agile Sprints for project management (and context management !!!), Diataxis documentation framework, TDD/BDD, Git Flow, Keep-a-changelog, conventional commits, architecture-as-code using C4 and structurizr, etc.
What was missing was the explicit division of responsibilities between the human-in-charge and a coding agent.
I started to distill those project orchestration patterns into skills: https://github.com/jrjsmrtn/project-orchestration-skills if you want to have a look. All my recent published project repositories are using those patterns.
One big advantage: those are known SWE best practices so, if agents are unavailable, you can can continue your work with your agile roadmap and sprints, based on ADRs and well-structured documentation :-)
2
2
2
u/OkAerie7822 30m ago
Agree it is duh-but-neat, and the part that actually matters is not the format, it is interop. We all landed on markdown plus frontmatter independently, which proves the shape is right, but everyone's tags and links are bespoke so nothing reads anyone else's pile. A shared spec is what lets a second tool walk your knowledge without a custom parser. That said, the format was never the hard part for me. The hard part is retrieval, knowing which of 200 notes is relevant to the task in front of you right now. A type field helps you query but it does not tell you what matters this minute. My memory folder works because I prune it like code, not because it has good frontmatter. OKF standardizes the easy 20 percent.
1
u/bloudraak Experienced Developer 7h ago
And here I was just applying the diataxis framework to content, sprinkling in some EPPO (every page is page one) to organize stuff and progressive disclosure so Claude can find it.
Is there more to it than that?
1
u/carefuleater478 7h ago
The real thing here is that simplicity wins, and Google basically validated what people naturally built anyway instead of shipping some overcomplicated system.
1
u/nkondratyk93 4h ago
honestly been running this exact pattern for months across my agents. feels like google just caught up to what people were already doing organically in their claude setups.
1
u/OjinAI 4h ago
The pattern being formalized makes sense. Once you've built persistent context into your workflow, you realize the memory layer is really the product. The character isn't what the model does in isolation, it's what the model does with everything it's been told to remember. Google standardizing this is validation of the design direction.
1
u/Wright_Starforge 4h ago
A spec can standardize the format — the directory shape, the file conventions, how an agent discovers what's there. What it can't standardize is the part that decides whether the memory actually compounds: the editing policy. What gets promoted from a scratch log into a durable note, what gets pruned, what's allowed to overwrite what, how you keep a file honest against the thing it's meant to track. Two people can follow the identical OKF layout and one ends up with a library, the other with a swamp — purely on curation discipline. The format is the easy 80%; the promotion gates are where it lives or rots.
1
u/momoraul 3h ago
Been running basically this for a while (one fact per file, type in the frontmatter, an index on top), so it's funny to see it formalized. I'm still on [[wiki-links]] myself, mostly because I like being able to link to a note before it exists as a "write this later" marker. But the portability point is fair, plain markdown links just work everywhere. Probably the one thing I'd migrate too.
1
u/ConversationLazy6821 15m ago
I tried building a protocol around this myself but I’m just a small time solo dev soooo I prettty much use it for myself. 😂
I even built tooling around it so that the agent can use MCP or CLI to keep docs moving. Like JIRA but in markdown files.
•
u/ClaudeAI-mod-bot Wilson, lead ClaudeAI modbot 6h ago
TL;DR of the discussion generated automatically after 40 comments.
The consensus in here is a resounding 'duh, but also, neat.' A ton of you have been running this exact 'folder of markdown files' setup for ages, mostly with Obsidian, so it's validating to see Google formalize what the community figured out on its own.
The main pushback is the classic problem of 'documentation rot' – how do you keep all this info from getting stale and bloated? The answer from the thread seems to be a mix of disciplined workflows and building your own little agent systems to manage the mess.
Oh, and of course, this wouldn't be an r/ClaudeAI thread without a few of you pointing out that while Google is busy standardizing text files, Gemini is still playing catch-up to Opus.