Here's a test you can run on your agent stack today: try to read one of your agent's memories with cat.
If you can't — if the answer involves a vendor dashboard, an API call, or exporting JSON from a vector database — your agent's accumulated knowledge is in a format that only one tool on Earth can fully interpret. That's fine right up until you switch tools, need an audit trail, want a backup you can actually inspect, or try to share knowledge between two agents built on different frameworks.
This post is about a fix that's been quietly gaining traction: the Open Knowledge Format (OKF), an open spec Google Cloud published in June for representing agent knowledge as plain markdown files with YAML frontmatter. I'll skip the industry commentary and focus on what it looks like, why plain files beat proprietary stores for a surprising number of jobs, and five concrete workflows you can set up this week.
The anatomy of an OKF memory
An OKF bundle is just a directory of markdown files. Each file is one unit of knowledge, with metadata in YAML frontmatter and the content in the body. A memory exported from a real system looks something like this:
---
type: preference
title: "User prefers TypeScript examples"
created: 2026-05-14T09:32:00Z
tags: [coding-style, typescript]
x_memanto:
provenance: session-8f3a
valid_from: 2026-05-14
recall_count: 23
---
The user has consistently asked for TypeScript over Python
in code examples. Confirmed explicitly on 2026-05-14.
Three things worth noticing:
The spec is minimal by design. It defines the interoperability surface — how a file declares what it is — without dictating your content model. There's essentially one required field (type); everything else is convention. This restraint is why it has a chance of sticking where heavier standards haven't.
The x_ namespace pattern handles tool-specific data. Anything your memory system tracks beyond the base spec (provenance, temporal validity, retrieval stats) goes under a namespaced block like x_memanto above. Other tools ignore what they don't understand but preserve it, so round trips through foreign tools don't destroy data. If you've worked with HTTP X- headers or Kubernetes annotations, this is the same idea.
The whole thing is text. Which means the entire Unix toolbox — and git — works on your agent's brain. That's where it gets fun.
Workflow 1: Version-controlled memory
The most immediately useful pattern: sync your agent's memory into a git repo.
# with a tool that supports OKF sync (Memanto shown; adapt to yours)
memanto memory sync --okf ./agent-memory
cd agent-memory && git init && git add . && git commit -m "baseline"
From here, standard git answers questions that are otherwise painful or impossible:
# What did my agent learn this week?
git log --since="1 week ago" --stat
# What exactly changed in its understanding of the billing module?
git diff HEAD~5 -- knowledge/billing/
# It learned something wrong on Tuesday. Undo it.
git revert <commit>
That last one deserves a pause. In most memory systems, correcting a bad memory means hunting it down through an API and hoping nothing else derived from it. With file-based memory under version control, a wrong learning event is a commit, and commits are revertible. Memory debugging becomes source control, a skill your whole team already has.
Workflow 2: Pull-request review for what your agent learns
Once memory is files in a repo, you can gate changes the same way you gate code. Run sync on a branch, open a PR, and a human reviews the diff of what the agent picked up before it's merged into canonical memory.
This sounds heavyweight until you need it. If your agent operates in a regulated domain — finance, health, anything with compliance officers — "show me exactly what the system learned and who approved it" stops being an impossible question. The answer is a PR history. You can even wire up CODEOWNERS so changes to certain memory types (say, anything tagged policy) require review from a specific team.
Workflow 3: CI checks on memory quality
Files in a repo means CI runs on them. A few checks that pay for themselves quickly:
# .github/workflows/memory-lint.yml (sketch)
- name: Validate frontmatter
run: python scripts/validate_okf.py ./agent-memory
Useful validations: every file parses as YAML+markdown, every file declares a type, no two files make contradictory claims with overlapping validity windows, timestamps are timezone-aware, and no memory references a session ID that doesn't exist in your logs. A 50-line validation script catches entire classes of memory corruption before they reach production — the kind of silent drift you'd otherwise discover months later through weird agent behavior.
(Speaking from experience: temporal metadata is where the bugs hide. Date-only timestamps that resolve to midnight instead of covering the full day, naive-vs-aware timezone mismatches, duplicates from delete-and-recreate flows. Lint for these specifically.)
Workflow 4: One knowledge base, many agents
Multi-agent setups usually grow parallel memory silos — the support agent knows things the sales agent doesn't, and keeping them consistent means custom glue. With an open format, the shared knowledge is just a bundle both agents import:
# hand-curated or exported from any OKF-speaking tool
memanto migrate support-agent --okf ./shared-knowledge
memanto migrate sales-agent --okf ./shared-knowledge
Because the bundle is markdown, non-engineers can maintain it. A product manager editing a markdown file in the GitHub web UI is now updating agent knowledge — no admin panel, no ticket to the AI team. Progressive-disclosure conventions (an index.md that points into detail files) keep large bundles navigable for both humans and models.
Workflow 5: Real backups and real exits
The dull one, and the one you'll be gladdest to have. An OKF export is a backup you can inspect without a running service — five years from now, those markdown files will still open, whatever happened to the tool that wrote them. And if you change memory systems, an open bundle is your migration path: export from tool A, import into tool B, without writing a bespoke ETL script against two proprietary APIs.
When you evaluate memory tooling, test the round trip, not the export checkbox: export, re-import, and diff. If data is missing after the round trip — temporal fields dropped, provenance gone — the export is lossy, and lossy export isn't portability, it's a screenshot. The x_ namespace exists precisely so implementations have no excuse for this. (This was the hard requirement we set when adding OKF support to Memanto, and I'd hold any tool, ours included, to it.)
When plain files are the wrong answer
Educational honesty requires the counter-case. File-based memory is not a retrieval engine: at scale you'll still want an index or embedding layer on top for semantic search — the bundle is the source of truth, not the query path. High-write-frequency working memory (per-turn scratch state) doesn't belong in git; commit-per-token is nobody's idea of fun. And OKF v0.1 is young — it deliberately doesn't standardize your memory taxonomy, so two tools can both "speak OKF" while modeling memories quite differently. The format guarantees you can read everything; semantic interoperability is still maturing.
A reasonable architecture treats OKF as the durable, auditable at-rest layer, with whatever retrieval and working-memory machinery you like above it. The format's job is to make sure the machinery is replaceable.
The takeaway
The agent ecosystem is repeating a pattern the software industry has run many times: capabilities first, interoperability later, and the teams who adopted open formats early skipped a painful migration era. You don't need to bet on any particular tool to benefit. Start with one habit: get your agent's memory into files you can cat, diff, and git log. Everything else in this post follows from that.
If you try any of these workflows — especially the PR-review or CI-lint patterns — I'd genuinely like to hear how they hold up in your stack. Drop a comment.
The examples above use Memanto (open source, MIT — pip install memanto), which supports OKF export, sync, and import natively, but every workflow here works with any tool that reads and writes OKF bundles — or with a bundle you build by hand in a text editor. That's rather the point.
Top comments (0)