OKF: A Package Manager and Lock File for AI Agent Memory

AI coding agents often "forget" shared architectural decisions and domain constraints when working across multiple codebases. System prompts keep growing longer, and vector databases lack the structured relationships needed to enforce strict, immutable rules. An open-source project called okf-agent-memory aims to solve this with a "package manager + lock file" approach.

The Problem: Why Agent "Memory" Is Unreliable

In autonomous coding scenarios, teams often face an awkward situation: the same architectural convention (say, a JWT token-binding rule) needs to stay consistent across multiple repos, but the agent has to "relearn" it every time.

There are two common approaches. One is stuffing every rule into the system prompt, which causes the prompt to balloon and maintenance costs to skyrocket. The other is leaning on a vector database for semantic retrieval, but vector search excels at "finding similar things" and struggles to express strict structural relationships like "A depends on B, C overrides D" — which is exactly the essence of architectural constraints.

OKF (Open Knowledge Format) starts precisely here: managing and versioning agent knowledge as code dependencies.

Vector databases and vector retrieval: Vector databases (such as Pinecone, Milvus, pgvector) map text, code snippets, and other content into high-dimensional dense vectors via embedding models, then retrieve by cosine similarity or dot product using approximate nearest neighbor algorithms (ANN, such as HNSW or IVF). Their strength is fuzzy semantic matching — even if the query terms and the document use completely different words, semantically close results can still be recalled. But structurally, they are essentially a "similarity table," not a "relationship graph": they cannot natively express directed, transitive, constraint-bearing relationships like "A depends on B," "C overrides D," or "this rule cannot be overridden." More critically, retrieval results are sensitive to embedding model versions, chunking strategies, and index update timing — the same knowledge may return different rankings in different environments, which runs counter to the reproducibility that OSes and build systems require.

How OKF Works: pull, vendor, lock

The core design of okf-agent-memory borrows from package managers like npm and cargo. According to the project's introduction on Reddit, the workflow is roughly as follows:

Pulling dependencies via CLI:

okf pull <bundle>
okf pull github.com/owner/repo@v1.0.0

After pulling, the bundle is unpacked into the .okf/vendor/ directory and pinned by its SHA-256 hash in the okf.lock file. This is entirely consistent with how traditional package managers lock dependency versions — hash locking means that any change to the contents of a knowledge bundle can be detected.

Local project memory can directly reference concepts from vendor, for example @jwt/decisions/token-binding. A linter statically validates whether these cross-bundle links are valid. This point is worth noting: knowledge references are statically verifiable, rather than only discovering at runtime that some decision can't be traced to its source.

Lock files and content addressing: The concept of a lock file originates from npm's package-lock.json, Cargo's Cargo.lock, and Go's go.sum. It records the exact version and content hash (such as SHA-256) of each dependency, giving the installation process two properties: first, reproducibility — any machine at any time using the same lock file gets a byte-identical dependency tree; second, tamper resistance — as soon as upstream content changes, hash verification fails immediately. OKF transplants this mechanism onto "knowledge bundles," giving architectural decisions the same guarantees of determinism and integrity. Compared to querying a vector store at runtime for the "latest version," a lock file turns "the knowledge the agent sees" into a static artifact that can be reviewed, diffed, and committed to Git.

A Decentralized Publishing Approach

OKF takes a distinctly open-source-flavored strategy for distribution: there is no centralized account system. Anyone can publish a bundle by tagging a GitHub release with the okf-memory-bundle topic label.

This lowers the barrier to publishing and avoids registration and review processes. The trade-off is that discovery and trust mechanisms rely on community self-regulation — which bundles are worth pulling is currently judged mainly by the credibility of the source repository. The project also provides a web directory (registry.okf-memory.dev) as a browsing entry point.

What v0.6.1 Brings

The current toolchain version is okf-agent-memory v0.6.1, with changes mainly focused on polishing retrieval quality:

• Native registry resolution: the CLI can resolve dependencies directly from the registry
• Deterministic retrieval optimization: fixed asymmetric DF/TF scoring, handled abbreviation suppression and prefix boundary cases
• Persistence fixes: contributed by the community

These improvements may sound trivial, but they are critical to the goal of "determinism." OKF repeatedly emphasizes that it is a deterministic, local-first memory model — the same input should yield the same retrieval results, rather than being affected by embedding models and index state like vector retrieval.

DF/TF in deterministic retrieval: DF (document frequency) refers to how many documents a term appears in, while TF (term frequency) refers to how many times it appears in a single document. Classic TF-IDF scoring is a weighted product of the two, used to measure how distinctive a term is for a given document. When OKF mentions "fixing asymmetric DF/TF scoring," it refers to a mismatch in the weights or normalization of these two factors in the ranking function, causing a small number of high-frequency or rare terms to produce counterintuitive rankings. Abbreviation suppression means avoiding splitting an abbreviation and its full form into two mutually interfering terms; prefix boundaries involve ensuring jwt does not falsely match superstrings like jwtxyz. These details directly determine "whether the same query on the same input always returns the same ranking" — precisely the foundation that OKF's promised determinism depends on.

Who This Approach Is For

From its design orientation, OKF is better suited to teams with clear architectural constraints and a strong need for cross-repo reuse. If your pain point is "the agent keeps making mistakes on the same architectural issue" rather than "the agent can't find relevant documentation," then an approach based on structured references and lock files may be a better fit than a vector database.

Conversely, if the knowledge itself is fuzzy, exploratory, and lacks clear boundaries, forcing structure onto it will only increase maintenance burden.

The project author ends the post with an open question: how do other teams distribute and version shared domain memory across repos? This is, in fact, a question for which the entire agent engineering field has yet to form a standard answer. The "package manager" analogy offered by OKF is one of the less common approaches available today.

Local-first and deterministic: Local-first means the authoritative copy of data is stored on local disk rather than on a remote server, with the network used for synchronization rather than as the sole source of truth. Combined with the requirement for determinism, the two together mean: the contents of .okf/vendor/ and the okf.lock hash that the agent reads at each startup are completely identical, and the retrieval algorithm does not depend on random initialization, external index state, or cloud model versions — so the same query yields the same result in CI, on a developer machine, and in a production container. This is especially important for scenarios requiring auditing, reproducibility, and regulatory compliance, and it is also the most fundamental divide between OKF and "cloud vector memory services": the former treats memory as version-controllable infrastructure, while the latter treats memory as a black box that may drift.

One-line Summary

OKF uses a "package manager + lock file" approach to manage architectural knowledge shared across repos by AI agents.

Paragraph Summary

OKF (Open Knowledge Format) is an open-source project that attempts to solve the problem of AI coding agents "forgetting" shared architectural decisions and domain constraints across multiple codebases. It treats agent knowledge as code dependencies, pulling bundles via okf pull, unpacking them into .okf/vendor/, and pinning them with SHA-256 hashes in okf.lock to achieve version locking and content verification. Local memory can be statically referenced through paths like @jwt/decisions/token-binding, with a linter validating cross-bundle links to avoid problems only surfacing at runtime. The publishing mechanism is fully decentralized, requiring only tagging a GitHub release with okf-memory-bundle. Compared to vector databases, which excel at "finding similar things" but struggle to express structural relationships, OKF emphasizes determinism and local-first operation, making it better suited to teams with clear architectural constraints and a strong need for cross-repo reuse.