okf-agent-memory Adds Git-Native Agent Memory

By Rogier Muller09.06.26

okf-agent-memory is an MIT-licensed open-source Go project from the okf-memory maintainers that stores AI coding agent memory as Markdown files inside a repository. It deals with a boring, expensive problem in agentic coding: agents forget useful project context when the chat or context window ends. The useful idea is simple: put durable memory in Git, retrieve only what matters, and make the agent's memory reviewable like code.

Git-native agent memory is persistent project knowledge stored as normal repo files, versioned and reviewed with the code they describe. That is the small but important difference between okf-agent-memory and a hidden long-term memory layer. Cursor, Anysphere's AI code editor, already gives developers a reviewable place to work with coding agents; this project asks whether the agent's remembered facts should live in that same workflow. GitHub Copilot Workshop is part of Harness Institute.

Keep memory where code review already happens

okf-agent-memory creates a knowledge/ directory of plain Markdown files with YAML frontmatter. The README describes it as a domain-neutral memory layer based on Open Knowledge Format v0.2, with an embedded MCP server and in-memory BM25 search.

That matters because project memory is usually split across three awkward places. Some rules live in AGENTS.md. Some live in tool-specific files like Cursor rules. Some live only in the agent's last conversation, which is the worst place to store an architectural decision.

The project is trying to occupy the middle ground. It is more structured than a pile of notes, but less opaque than a vector database. As of September 5, 2026, the GitHub repository showed 131 stars, was mainly Go, used the MIT license, and had been pushed that day.

The trap is treating this as a replacement for repo rules. It is not. Use durable rules for behavior boundaries, and use okf-agent-memory for facts the agent should retrieve when they become relevant.

A clean split in a Cursor repo might look like this:

AGENTS.md                  # always-on repo boundaries
.cursor/rules/api.mdc      # Cursor rule for API work
knowledge/decisions/*.md   # remembered decisions and discoveries
knowledge/ops/*.md         # operational facts the agent may need later

Progressive disclosure is the clever part

The interesting claim in okf-agent-memory is not just persistence. It is progressive disclosure: search the memory first, then feed the agent only the small slice that matches the task.

The README claims sub-300µs in-memory BM25 search and an 80% token reduction in its benchmark path. It also ships a benchmark runner so you can test Time-To-First-Token behavior locally with tools such as Ollama or LM Studio and models such as Gemma, Qwen, or Llama.

That is a sane direction. Long memory is not helpful if it becomes a second prompt dump. A coding agent needs the payment retry decision when editing checkout code, not when renaming a CSS class.

The trap is believing search precision solves truth. A stale memory file can be retrieved very quickly and still be wrong. If a memory entry affects code behavior, it should have a date, owner, and review path, not just a confident sentence.

Here is the kind of memory entry I would trust more than a free-form note:

---
type: decision
area: billing/retries
status: active
last_reviewed: 2026-09-05
---

We retry failed card authorization once after 30 seconds.
Do not add client-side retry loops; retry logic belongs in the billing worker.

Evidence: billing worker handles idempotency with payment_attempt_id.

The rough edge is scope, not speed

The first pushback developers had was predictable: repo-local memory is great, but what about cross-project memory? If you work across five services, you may want the agent to remember platform-wide conventions once.

That is a real limitation. okf-agent-memory's Git-native shape is strongest when knowledge belongs to one repo: architecture decisions, domain terms, migration notes, operational caveats. Cross-project memory needs a boundary model, or it can become a leaky bucket of half-true conventions.

This is where MCP matters. Model Context Protocol is a standard way for AI applications to connect to external tools and context servers. okf-agent-memory includes an MCP server, which makes the memory layer reachable by MCP-capable coding tools without requiring the memory to become a proprietary feature.

Still, cross-project memory should be treated as a separate product question, not a checkbox. A shared memory for all repos needs permissions, freshness, and conflict handling. That is closer to the context-registry problem explored in Show HN: APIMatic’s Context Registry for Coding Agents than a simple folder convention.

Try it on one small repo

The safest first test is a small repo with real history and one annoying recurring decision. Do not start with your monorepo. Pick a service where agents often re-ask the same architecture question.

Clone the project, build the tool as described in the repository, and run the benchmark path before wiring it into daily work:

git clone https://github.com/okf-memory/okf-agent-memory
cd okf-agent-memory
make benchmark

Then create two or three memory files by hand. Keep them boring. One decision, one domain glossary entry, and one operational caveat is enough.

For Cursor users, add a local rule that tells the agent how to treat memory. Cursor rules should be small and specific, not a second documentation site.

---
description: Use repo memory only as reviewed context
alwaysApply: false
globs:
  - knowledge/**/*.md
---

When a task may touch architecture, domain behavior, or operations, inspect relevant files under knowledge/ before proposing code.

Treat memory files as context, not authority. If memory conflicts with source code, tests, or AGENTS.md, stop and ask for review.

When changing behavior based on a memory entry, mention the memory file in the final summary.

That rule gives you a review hook. If an agent changes billing code because of knowledge/decisions/retry-policy.md, the final summary should say so. This is the practical seam between developer productivity and agentic coding governance: the agent can use memory, but the reason remains inspectable.

A small checklist before trusting the memory

Copy this into the first pull request that adds okf-agent-memory-style files to a repo. It is intentionally small. The point is to test whether memory improves the agent's work without turning the repo into a bureaucracy.

## okf-agent-memory first-test checklist

Repo chosen:
Task chosen:
Agent/tool used:

Memory files added:
- [ ] One active architecture decision
- [ ] One domain glossary entry
- [ ] One operational caveat

Review checks:
- [ ] Each memory file has a type, area, status, and last_reviewed field
- [ ] No secrets, credentials, customer data, or private incident details are stored
- [ ] AGENTS.md still owns behavior rules and safety boundaries
- [ ] Cursor rule tells the agent to cite memory files in its summary
- [ ] Agent output was compared against source code and tests

Pass condition:
- [ ] The agent used less prompt context or asked fewer repeat questions
- [ ] The memory did not override code, tests, or current docs
- [ ] A reviewer could understand why the agent made the change

The main thing to check is not whether the search is fast. It probably is. Check whether the retrieved memory made the agent more accurate, and whether a human reviewer could see that influence without replaying the whole chat.

Common questions

Is okf-agent-memory a vector database replacement?

No, okf-agent-memory is closer to a repo-native memory format with fast keyword retrieval than a managed vector database. Its README emphasizes Markdown files, YAML frontmatter, in-memory BM25 search, and no external database, which makes it easier to review but less like semantic memory infrastructure.

How is this different from AGENTS.md or Cursor rules?

AGENTS.md and Cursor rules are best for instructions, boundaries, and local conventions. okf-agent-memory is better suited to remembered facts: decisions, discoveries, glossary entries, and operational notes. The useful pattern is layered: rules tell the agent how to behave, memory gives it relevant project context.

Can it handle cross-project memory?

Not as the primary shape today. The repo design is strongest when memory belongs to the code beside it, which keeps review and freshness clear. Cross-project memory would need stricter permissions, conflict handling, and ownership, especially when the same term means different things in different services.

Should I connect it through an MCP server?

Use the MCP server if your coding environment can call MCP tools and you want memory retrieval inside the agent workflow. MCP is useful because it gives tools a common integration surface, but the safer first test is still read-only memory access on one repo.

What should I avoid putting in memory?

Do not store secrets, customer data, credentials, private incident details, or anything that should expire silently. Memory files are Git files, so they are durable, copyable, and reviewable. That is a feature for architecture notes and a liability for sensitive operational data.

Best ways to use this research

Best for: Engineers comparing repo-local memory patterns for coding agents, especially where reviewability matters more than hidden personalization.
Best first artifact: Add three knowledge/ files and one Cursor .mdc rule, then ask the agent to cite any memory it used in the final summary.
Best comparison angle: Compare okf-agent-memory against plain AGENTS.md notes and a vector database on freshness, reviewability, retrieval quality, and setup cost.
Best failure test: Change source code so it contradicts an old memory entry, then see whether the agent follows the stale note or stops to flag the conflict.

Next step

Try okf-agent-memory on one small repo with one repeated architecture decision. If the agent can use the memory and explain its use in review, the idea is worth a deeper look.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.