Git-native agent memory needs governance, not just Markdown

Agent memory has become a shared-state problem

A coding agent can rediscover an architecture decision, repair a failure, and explain an obscure deployment constraint. When the session ends, that work either disappears or becomes memory. The dangerous case is not forgetting. It is remembering a conclusion after the code, policy, owner, or evidence has changed.

Google introduced the Open Knowledge Format in June 2026 as a minimally opinionated way to exchange knowledge: Markdown documents, YAML frontmatter, ordinary links, optional indexes, and logs. Version 0.2, published in July, moved trust concerns into the format. It added first-class provenance, verification, freshness, lifecycle, actor, and attested-computation concepts while keeping type as the only field every concept must contain.

Developer interest is now producing independent tooling. In a September 9 focused scan, the Go-based okf-memory/okf-agent-memory repository had 493 stars and appeared in a Hacker News item; serradura/okf had 155 stars. Other projects are experimenting with draft promotion, code-grounded verification, compiled snapshots, deterministic search, MCP access, and multi-actor workflows. These counts show a live implementation wave, not proof that one design has won.

The practical thesis is narrower: a repository is a useful trust surface because teams already know how to review diffs, identify authors, run checks, preserve history, and revert commits. But Git is not a truth engine. A polished Markdown note can still be unverified, stale, contradictory, malicious, overshared, or retrieved for the wrong task.

What OKF v0.2 standardizes, and what it leaves open

An OKF bundle is a directory of concept documents. Each document is Markdown with YAML frontmatter. Directories may contain an index.md for progressive disclosure and a log.md for chronological changes. Standard Markdown links form relationships. A consumer can read a file directly, build a search index, render a graph, or expose the bundle through MCP without changing the representation.

---
type: Decision
title: Payment webhook idempotency
description: Reuse provider event ID as the durable deduplication key.
tags: [payments, webhooks, reliability]
generated:
  by: coding-agent/2026-09-09
  at: 2026-09-09T01:40:00Z
sources:
  - resource: ../references/payments-api.md
    author: human:platform-docs-owner
    last_modified: 2026-09-08
verified:
  - by: process:webhook-contract-test
    at: 2026-09-09T02:05:00Z
status: active
stale_after: 2026-12-09
---

Use the immutable provider event ID as the insert key.
Retry handlers must return the prior result for a duplicate event.

This document is portable and inspectable. It tells a consumer who generated it, which source supports it, what process verified it, whether it is active, and when it should be reconsidered. The v0.2 specification deliberately records objective signals rather than a universal credibility score. Different consumers can apply stricter or looser policies without rewriting the source file.

The specification does not define who may write, whether two edits can merge, how a repository maps to tenants, which source outranks another, how retrieval ranks concepts, what counts as a successful verification, or whether an agent may act on the result. It also does not replace domain schemas such as OpenAPI or Protobuf. OKF can point to those artifacts and carry contextual knowledge around them; it does not subsume them.

Separate capture from promotion

The safest write path has at least four states: draft, candidate, active, and withheld. An agent writes an attributed draft after a task. A deterministic process validates its shape, source references, links, and forbidden content. A reviewer or approved verification process promotes a candidate only after checking that it is durable, specific, non-duplicative, and supported by the current system. An active concept moves to withheld when its source changes, its expiration passes, or a contradiction appears.

function promote(candidate, repositoryState) {
  require(candidate.generated.by)
  require(candidate.sources.length > 0)
  require(noSecrets(candidate))
  require(validateLinks(candidate, repositoryState))
  require(noActiveConceptWithSameScope(candidate))

  const evidence = verifyAgainstLiveSystem(candidate)
  if (!evidence.passed) return withhold(candidate, evidence.reason)

  return {
    ...candidate,
    status: "active",
    verified: [...candidate.verified, evidence.receipt],
    promoted_from: repositoryState.commit,
    stale_after: chooseReviewDate(candidate.type)
  }
}

Do not let the model approve its own prose by asking it whether the note looks correct. Useful verification is independent of the claim generation path. A code decision can reference a passing contract test and exact commit. A runbook can require a human owner plus a successful drill. A metric can use an OKF attested computation whose executor emits a receipt and whose deterministic attester checks the method.

Promotion granularity matters. One concept should express one durable claim or operating rule. A session summary that mixes seven fixes, speculation, preferences, and customer details is hard to verify and dangerous to retrieve. Break it into atomic concepts, discard ephemeral narration, and route personal preferences to a different scope from shared project facts.

Make multiple writers explicit

Git handles textual concurrency by producing merges and conflicts. Knowledge concurrency is semantic. Two agents can edit different files without a Git conflict while creating contradictory active instructions. One says the deployment runs in us-east-1; another says eu-west-1. Both commits can merge cleanly and still poison future work.

Assign an authority scope to each concept family. Code-derived facts may be proposed by agents but promoted by tests or maintainers. Security policy needs the security owner. Product definitions need the relevant business owner. Actor-specific preferences stay in an actor namespace and never override repository or organization policy. Use optimistic concurrency on the bundle revision and run semantic conflict checks over concept IDs, resources, tags, and declared supersession edges before merge.

Prefer append-and-supersede for consequential decisions. Editing the old conclusion in place hides the path by which it changed. A new concept can declare that it supersedes the old one, cite the change, and preserve the prior state for reproducibility. Default retrieval follows only active heads; incident analysis can still reconstruct what an agent knew at the earlier commit.

Progressive disclosure is a control, not only an optimization

Loading every memory into every prompt increases cost and makes instructions compete. OKF indexes allow an agent to inspect a small map before opening concepts. Independent implementations add BM25, FTS, graphs, and compiled snapshots. These tools can reduce latency and context use, but repository-authored benchmark numbers are not neutral comparisons. Reproduce them with your corpus, hardware, cold-start behavior, query distribution, and acceptance tests.

Retrieval should filter before it ranks. Remove concepts the actor cannot access. Withhold stale, superseded, quarantined, or incompatible-version entries. Match project, branch, environment, tenant, and task type. Then rank the remaining set and enforce a token or concept budget. Return provenance and status with the content so the agent can decide whether it needs a fresher source.

Lexical search is predictable and cheap when the vocabulary is stable. Semantic retrieval helps when users phrase the same idea differently, but it adds an embedding model, index lifecycle, and potential cross-boundary leakage. A practical hybrid uses deterministic metadata and scope filters first, lexical candidates second, optional semantic expansion third, and a confidence gate before injecting any result.

Freshness cannot be a date alone. A concept tied to src/auth/session.ts should be withheld when that file or named symbol changes. A vendor API rule should expire on a short interval or changelog event. A durable business definition may survive for a year but still require an owner. A runbook should be reverified after every incident or drill. Use source fingerprints and event-triggered invalidation where possible, then keep stale_after as a backstop.

Worked example: two correct memories become one wrong action

An agent fixes a billing webhook and records: “retry events are safe because writes use the provider event ID.” The contract test passes, so the concept is promoted. Three weeks later, another agent migrates writes to a queue and records: “workers deduplicate by message ID.” That statement is correct for queue delivery, but the provider can resend the same event in a new message. The files have different names and merge without conflict.

A future agent retrieves both notes, assumes two independent dedupe layers exist, and removes the database uniqueness constraint. The next provider retry creates a duplicate credit. Every sentence in memory was once locally defensible; the combined inference was wrong because scope, supersession, and end-to-end verification were missing.

The controlled workflow binds each claim to a resource and invariant. The migration change triggers staleness for the webhook concept. A semantic check sees that both concepts cover billing-event-deduplication. The candidate note must either supersede the prior decision or narrow itself to queue transport. An end-to-end retry test confirms that provider event ID remains the business key. Only then does the new concept become active.

The release receipt records the bundle commit, code commit, tests, promoted concept IDs, withheld concept IDs, reviewer, and rollback point. If the production incident occurs anyway, the team can reproduce which memory set the agent saw rather than asking a model to summarize a chat transcript after the fact.

Treat the knowledge repository as executable context

Memory can influence code edits, commands, credentials, deployments, and customer communication. That makes it an indirect control plane. Protect default branches, require review for trusted paths, scan drafts for secrets and prompt injection, pin external references where appropriate, and separate public, internal, confidential, and regulated bundles.

Do not expose a write-capable memory MCP server to every agent by default. Separate read tools from draft-creation tools and keep promotion outside the model session. Log concept IDs returned to the agent and which ones shaped an action. A malicious repository file, copied issue, or external document must remain evidence with provenance, not silently become a standing instruction.

Rollback is also scoped. Reverting the knowledge commit does not undo actions already taken from that memory. Pair memory history with execution receipts and external-system reconciliation. When a concept is compromised, withhold it, identify every session that retrieved it, inspect downstream effects, repair the live system, and only then promote a corrected concept.

Failure modes to test before rollout

A 30-day adoption checklist

1. Define memory scopes, concept types, owners, confidentiality classes, retention, and forbidden content before installing tooling.
2. Start with read-only curated knowledge. Measure whether agents retrieve useful concepts and ignore irrelevant ones.
3. Adopt OKF v0.2 fields for sources, generated actor, verification, status, and freshness where they add real evidence.
4. Create a separate draft path. Do not allow a task agent to mutate the trusted lane directly.
5. Build deterministic validation for YAML, required fields, links, duplicate IDs, cycles, secrets, and lifecycle transitions.
6. Bind code-related concepts to commits, files, symbols, tests, or other recheckable sources.
7. Define optimistic concurrency and semantic conflict checks for multiple writers and repositories.
8. Filter by permission, scope, compatibility, and lifecycle before ranking or semantic search.
9. Log the bundle commit and retrieved concept IDs in agent execution receipts.
10. Test poisoned drafts, stale code facts, contradictory decisions, missing sources, cross-tenant retrieval, and rollback.
11. Compare retrieval quality and accepted task outcomes, not only query latency or token reduction.
12. Promote write access gradually and keep a named curator plus emergency withholding path.

Choose an implementation after testing the same bundle and scenarios across candidates. The format is intentionally portable, so switching tools should not require rewriting the knowledge. Preserve that advantage: keep vendor-specific indexes and caches rebuildable from the reviewed OKF source rather than making them the only copy.

Frequently asked questions

What is the Open Knowledge Format?

OKF v0.2 is a vendor-neutral representation for knowledge bundles made of Markdown files with YAML frontmatter. It standardizes structure, provenance, trust signals, lifecycle, and related conventions. It is not a database, vector index, permission system, or agent runtime.

Should an AI agent write directly to shared memory?

Let agents write attributed drafts. Promotion to the default trusted lane should require schema checks, source verification, conflict detection, live-system evidence, and the authority appropriate to the concept.

Does Git make agent memory trustworthy?

Git makes change inspectable and reversible. It cannot establish truth, freshness, authorization, confidentiality, or task relevance. Those need separate controls.

Is BM25 enough for agent memory retrieval?

It can be excellent for stable technical vocabulary and deterministic behavior. Evaluate it against your queries. Add semantic expansion only when it improves accepted retrieval outcomes without weakening permissions or predictability.

When should stale memory be deleted?

Withhold it from normal retrieval first. Preserve its history for audit and reproducibility until retention policy and an authorized owner permit deletion. Use supersession when a newer concept replaces it.