OKF Agent Memory is a free, open-source command-line tool that gives Claude Code, Cursor, and other AI coding agents a persistent memory folder stored as plain Markdown in your git repo, searchable in under a millisecond with no external database. It ships as a single Go binary, runs entirely on your machine, and connects to your agent through its own built-in MCP server.
Short answer: OKF Agent Memory is an open-source CLI (MIT license) that stores AI agent memory as version-controlled Markdown files in a
knowledge/folder, indexed with local BM25 search instead of a vector database. It bootstraps into any repo in seconds, plugs into Claude Code or Cursor over MCP, and its maker claims roughly 80% lower token usage versus dumping full context files into every prompt.
I pulled the v0.1.0 release the day it hit Hacker News, ran it against a scratch repo, and tried to break it before deciding whether it belongs in a real project. It's rough in a few spots you'd expect from a two-day-old tool with 208 GitHub stars, but the core idea — memory that lives in git instead of a database — held up. The project's own README, on GitHub, lays out the pitch as "zero external databases or dependencies," which matches what I saw running it offline.
What you'll need
You need a 64-bit Linux, macOS, or Windows machine and about five minutes; there's no Go toolchain requirement since the release ships pre-built binaries for both amd64 and arm64. You'll also want a git repository to test in, since the whole pitch is that memory updates show up as ordinary diffs. On the agent side, OKF Agent Memory's MCP server works with Claude Code, Cursor, and Codex out of the box, plus any local model runner (Ollama, LM Studio) that can speak MCP over stdio. Nothing here requires an account, an API key, or a network connection after the install — the search index and the CLI both run fully offline.
Step-by-step: setting up OKF Agent Memory
1. Install the CLI
The maintainers publish a one-line installer:
“ curl -fsSL https://okf-memory.dev/install.sh | sh “
I skipped that and pulled the okf-linux-amd64 binary straight from the GitHub release instead, since I'd rather read a script before piping it into a shell on a machine I care about. Either way you end up with a single okf binary; running okf version should print okf version v0.1.0 (OKF v0.2 specification).
2. Bootstrap the knowledge bundle
Inside a project, run okf bootstrap . This scaffolds a knowledge/ folder with an index.md and log.md, an AGENTS.md file with instructions the agent reads automatically, a Makefile, and an .agents/skills/okf-memory/ folder with a ready-made skill. In my test this took under a second on an empty repo and didn't touch anything outside those four locations.
3. Create your first concept
okf create architecture/api-layer knowledge -type Fact -title "API Layer" -desc "REST routing and middleware conventions" -body "All routes live under /api/v1. Auth runs before rate limiting." writes a small Markdown file with YAML frontmatter (type, title, description, tags, and a generated: provenance stamp) and updates the parent index automatically. Running git diff --stat right after showed a two-line change to log.md and index.md — that's the entire footprint of adding a memory entry, which is the git-native pitch working as advertised.
4. Wire it into your agent
okf mcp knowledge starts the MCP server over stdio. Point Claude Code or Cursor at it the same way you'd add any local MCP server, using the binary path and the mcp knowledge arguments. Once connected, AGENTS.md tells the agent to search before writing (okf search "<query>") and to avoid bulk-scanning the knowledge/ folder with grep or list_dir, which is the mechanism behind the token-reduction claim — the agent pulls one 300-token concept instead of an entire context file.
5. Validate before you commit
okf validate knowledge --strict --drift checks for broken links, orphaned concepts, and index entries that no longer match their descriptions. On my four-concept test bundle it ran in 3 milliseconds flat, including process startup — not the sub-300-microsecond figure in the marketing copy, which measures the in-memory BM25 lookup alone, but still fast enough to run on every commit without noticing it.
Example prompts you can copy
Once the MCP server is connected, these are the prompts that got a real agent to use the memory layer instead of ignoring it:
- Force a memory check first: "Before you touch the auth code, search project memory for anything about authentication or middleware."
- Record a decision after the fact: "We just agreed to use pgx instead of an ORM for the database layer. Write that to memory as a Fact under architecture/db-layer."
- Audit what's stored: "Run okf validate on the knowledge bundle and tell me if anything is stale or orphaned."
- Link related concepts: "Relate architecture/api-layer to architecture/db-layer with a note that the API layer calls the DB layer directly."
- Sanity-check drift: "Check whether index.md's descriptions still match what's actually in each concept file."
Prompt 1 is the one worth making a habit — in my testing, an agent that isn't explicitly told to search first will often just re-derive an answer from the code instead of checking whether someone already wrote it down.
How it compares to other agent-memory approaches
| Approach | Storage | Search | Setup | Cost per query | Git-diffable |
|---|---|---|---|---|---|
| OKF Agent Memory | Markdown files in knowledge/ |
Local BM25, <300µs | Single binary, okf bootstrap . |
$0 (fully local) | Yes — plain text diffs |
| Plain AGENTS.md / CLAUDE.md | One flat file | None — full file loaded every time | Manual editing | $0, but token cost per prompt | Yes, but diffs get noisy fast |
| Mem0 / vector-DB memory | Embeddings in a vector store | Semantic (cosine similarity) | API key + hosted or self-hosted DB | Per-embedding API cost | No — binary/opaque store |
| mcp-memory (SQLite FTS5) | SQLite database | Full-text search | MCP server + SQLite file | $0, local | No — binary DB file |
The honest way to read this table: BM25 keyword search is cheaper and faster than a vector database, but it's lexical, not semantic — it won't find a concept described with entirely different words than the query. If your team writes clear, consistent titles and descriptions, that's rarely a problem. If your memory files are sloppy, a vector store will paper over the inconsistency in a way BM25 won't. The official OKF Agent Memory site also lists a claimed 5.2x faster time-to-first-token for local models like Ollama and LM Studio, since a smaller prompt reaches the model faster — I didn't have a local model rig to verify that number myself, so treat it as the vendor's figure, not mine.
Common mistakes to avoid
Flag order trips people up: okf bootstrap . -name "My Project" fails with a cryptic "flag needs an argument" error, because the CLI expects flags before the positional target directory — okf bootstrap -name "My Project" . is the form that actually works. I hit this on my first try and lost a few minutes to it. Second, don't skip okf validate --strict before committing; it's nearly instant and catches broken links between concepts that are easy to introduce by hand. Third, resist editing knowledge/ files directly for anything an agent will later "own" — the tool distinguishes generated: (agent-written) from verified: (human-confirmed) frontmatter, and hand-editing without updating that field defeats the trust-tier system that's most of the point. Fourth, don't expect the MCP integration to be automatic — you still have to point your agent's MCP config at the binary yourself, and a couple of Hacker News commenters reported inconsistent tool-calling behavior outside Claude Code and Codex, so test the connection before relying on it for anything important. Fifth, this is a two-day-old v0.1.0 release with 208 stars as of this writing — treat it as an early bet, not an infrastructure decision, until it's had more time in the wild.
Tools that make this easier
If you're setting this up inside Claude Code specifically, my how to use Claude AI guide covers the base setup this builds on top of, and AI coding agent skills for real engineers explains the SKILL.md format that OKF Agent Memory's bootstrap step installs automatically. For the MCP side of this, WebMCP: teaching your website to talk to AI agents is useful background on the protocol this tool builds its server on. If you're running multiple agents against the same repo and want memory that survives session handoffs, see Mission for Claude Code and, for the token-cost side of running agents at scale, Claude Code usage tracking by LangWatch. Anyone giving an agent write access to a live memory folder should also read an AI agent has root before deciding how much autonomy to grant it, and if you're testing this inside a disposable environment first, Docker sandboxes for AI agents is the safer way to try it before pointing it at a real codebase.
My take
For a solo project or a small team that already commits an AGENTS.md or CLAUDE.md file, OKF Agent Memory is a reasonable upgrade: it turns one growing file into a searchable, git-diffable folder without adding a database or a recurring API bill. What it isn't yet is a finished product — the flag-parsing quirk I hit, the thin real-world testing outside Claude Code, and the fact that it launched two days ago all argue for watching how the project matures before wiring it into anything you depend on. I'd try it on a side project before a production monorepo.
Frequently Asked Questions
Is OKF Agent Memory free?
Yes. The CLI is MIT-licensed and free to use, with no account or API key required. The maintainers mention a separate "OKF Cloud" enterprise beta for cross-repository features, available by request, but the core tool covered here costs nothing.
How long does it take to set up OKF Agent Memory?
In my testing, downloading the binary and running okf bootstrap . took under a minute on an existing repo. Wiring the MCP server into Claude Code or Cursor adds a few more minutes since you have to edit that agent's MCP configuration by hand.
What is the easiest way to try OKF Agent Memory?
Download the release binary for your platform from the GitHub releases page, run okf bootstrap . inside a throwaway repo, and create one test concept with okf create before deciding whether to connect it to a live agent.
Does OKF Agent Memory need a database?
No. It stores everything as Markdown files with YAML frontmatter and indexes them with an in-memory BM25 search built into the binary itself, so there's no SQLite file, vector store, or external service to run.
Does OKF Agent Memory work with tools other than Claude Code?
The maintainers list Cursor, Codex, Windsurf, and local model runners like Ollama and LM Studio as supported through its MCP server. Hacker News commenters noted that tool-calling reliability outside Claude Code and Codex hasn't been widely tested yet, so confirm your specific agent honors the MCP connection before depending on it.
Last updated: September 6, 2026 · By Vishal Swami, Founder & Lead AI Reviewer, AISagely