{"slug": "i-ported-a-knowledge-format-okf-library-to-zero-dependency-net-here-s-what-i", "title": "I ported a knowledge-format (OKF) library to zero-dependency .NET — here's what I learned", "summary": "A developer ported Google's Open Knowledge Format (OKF) library to zero-dependency .NET, creating OKF4net. The C# port produces byte-identical output to the original Rust implementation, verified through five golden CLI comparisons. The library enables reading knowledge bases from plain markdown files without vector databases or vendor lock-in.", "body_md": "If you can `cat`\n\na file, you can read the knowledge base. If you can `git clone`\n\na repo, you can ship it. No vector database to stand up, no proprietary export format, no vendor lock-in — just a directory of markdown files with YAML frontmatter that a human can open in any editor and an agent can read with `ReadFile`\n\n. That's the whole pitch, and it's the reason I spent the last few weeks porting a library to C# to get it onto .NET.\n\nThe format behind that pitch is Google's [Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md), and the library is [ OKF4net](https://github.com/jchable/okf4net) (\n\nOKF defines a **bundle**: a directory tree of UTF-8 markdown files, where each file is a **concept** — a YAML frontmatter block followed by a markdown body. Concepts cross-link each other with ordinary markdown links, `index.md`\n\nfiles give you progressive-disclosure directory listings, and `log.md`\n\nfiles record date-grouped change history. The only hard conformance requirement is a non-empty `type`\n\nfield on every concept; everything else — unknown types, unknown keys, broken links — has to be tolerated by a conformant consumer. It's deliberately boring as a format, which is the point: the format is context here, not the pitch. The pitch is what you get to do with plain files — diff them, review them in a PR, grep them, back them up with nothing but `git`\n\n.\n\nThis repository used to ship a Rust implementation of OKF. I removed it at commit `d20343c`\n\n— but only after proving, file by file and command by command, that the C# port produced byte-identical output. `tests/fixtures/golden/`\n\nholds five golden captures taken directly from the Rust binary's stdout — `validate`\n\n, `info`\n\n, `graph --dot`\n\n, `fmt`\n\n, and `index`\n\n— against a shared example bundle, and the C# CLI is diffed byte-for-byte against every one of them in CI. As of today the full suite passes end-to-end, including five byte-exact golden CLI comparisons against the original captures.\n\nI'll say the quiet part out loud: this port was AI-assisted, done largely with Claude Code driving the migration file by file, spec section by spec section, with the golden fixtures as the ground truth it had to match exactly. I think that's worth stating plainly rather than glossing over — a byte-exact port across languages is a fairly mechanical, well-specified translation task with an unambiguous pass/fail signal (does the output match the captured bytes, yes or no), which is exactly the kind of task where an AI pair-programmer earns its keep and where you can trust the result *because* you can verify it byte-for-byte rather than having to take anyone's word for it. The interesting design decisions — the YAML subset, the permissive-loading philosophy, the two-tier validation split — came from following the spec and the Python reference implementation; the AI assistance was in the grinding, get-every-byte-right execution, not the architecture.\n\nHere's the library, loading a bundle and running a conformance check:\n\n``` js\nusing OKF4net;\n\nvar bundle = Bundle.Load(\"./my_bundle\");\nConsole.WriteLine($\"{bundle.Count} concepts\");\n\n// Conformance check (§9).\nvar report = BundleValidator.Validate(bundle);\nif (report.IsConformant)\n{\n    Console.WriteLine($\"conformant with OKF v{OkfSpec.Version}\");\n}\n\n// Traverse the cross-link graph.\nvar id = ConceptId.Parse(\"tables/orders\");\nforeach (var link in bundle.LinksFrom(id))\n{\n    Console.WriteLine($\"{id} -> {link.Target} (exists: {link.Exists})\");\n}\n```\n\n`Bundle.Load`\n\nnever aborts on a malformed concept file — it collects parse failures into `bundle.ParseErrors`\n\nand keeps walking the tree, because a knowledge base that one bad file can take down entirely is a bad knowledge base.\n\nAnd here's the CLI, which is the same tool the Rust binary used to be, invocation-for-invocation:\n\n```\nokf validate ./bundles/ga4\nokf graph ./bundles/ga4 --dot | dot -Tsvg > graph.svg\n```\n\n`okf validate`\n\nexits non-zero on a non-conformant bundle, so it drops straight into a CI step. The CLI ships as a self-contained, Native AOT single-file binary — no .NET runtime install required on the machine that runs it.\n\nThe reason I care about this format enough to port a whole library for it is `OKF4net.Agents`\n\n, which turns an OKF bundle into tools and context for the [Microsoft Agent Framework](https://github.com/microsoft/agent-framework). `OkfBundleTools`\n\nwraps one bundle root and exposes nine function tools — read, browse, graph, search, write, append-log, regenerate-indexes, validate, changes-since — that an `AIAgent`\n\ncan call directly:\n\n``` js\nvar tools = new OkfBundleTools(\"./my_bundle\");\nAIAgent agent = chatClient.AsAIAgent(tools: tools.GetTools());\nvar response = await agent.RunAsync(\"Search the bundle for concepts about refunds.\");\n```\n\nLayer `OkfContextProvider`\n\nonto the same tools instance and, opted in explicitly, an agent's exchanges get captured as long-term memory — one markdown concept per UTC day, written through the same validated, lock-protected write path the tools use, plus a matching `log.md`\n\nentry. That's the part I think is genuinely different from the usual answer to \"give my agent memory\": instead of an opaque vector store you can't audit, memory is a markdown file in a git-tracked directory. You can open it, diff it across commits, redact a line, or point a second agent at the exact same directory with no export step. It's not a fit for every use case — the README is upfront that v1 memory is bundle-global and unscoped, so it's opt-in and meant for a shared, non-sensitive bundle rather than a multi-tenant deployment — but for a single team's shared knowledge base, \"memory you can `git blame`\n\n\" is a real capability, not a slogan.\n\nThe whole library — `OKF4net`\n\nand `OKF4net.Cli`\n\n— has zero third-party runtime dependencies: no YAML library, no CLI-parsing package, nothing. It has its own documented YAML *subset* parser (frontmatter is scalars, lists, and shallow maps — no anchors, no tags, no multi-document files, and it says so with a clear error if you hand it those), its own markdown link scanner, and its own argument parsing, all on top of the .NET base class library. That constraint is what makes the CLI publishable as a single-file Native AOT binary with no runtime to install, and it's what keeps the barrier to contributing low — there's no framework to learn before you can read the code. `OKF4net.Agents`\n\nis the one exception, since talking to `Microsoft.Agents.AI`\n\nrequires depending on it; everything else stays dependency-free by design, enforced project by project. The project also ships `OKF4net.Catalog`\n\n, a local multi-bundle catalog with search-by-source resolution, and `OKF4net.Mcp`\n\n, an MCP server that plugs a bundle straight into Claude Desktop or Claude Code — so agents and tools have a ready path to discover and query bundles without writing that plumbing themselves.\n\nOKF4net is young and I'd rather it stay welcoming than gate-kept. If you'd like to start by reading, the [project site and docs](https://jchable.github.io/okf4net/) are the friendlier entry point — a guided overview and getting-started walkthroughs.\n\nYou don't need any prior OKF knowledge to help — the [ good first issue](https://github.com/jchable/okf4net/labels/good%20first%20issue) label names the files to touch and the test that should go green when you're done,\n\n`ROADMAP.md`\n\n`dotnet build`\n\n, `dotnet test`\n\n, `dotnet format`\n\n. If any part of \"knowledge bundles you can `cat`\n\nand agents that remember things in files you can read\" sounds useful to you, I'd love the help — and the feedback.", "url": "https://wpnews.pro/news/i-ported-a-knowledge-format-okf-library-to-zero-dependency-net-here-s-what-i", "canonical_source": "https://dev.to/julien_chable/i-ported-a-knowledge-format-okf-library-to-zero-dependency-net-heres-what-i-learned-1mb7", "published_at": "2026-07-27 10:09:05+00:00", "updated_at": "2026-07-27 10:32:02.725471+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence"], "entities": ["Google", "OKF4net", "Claude Code", "Open Knowledge Format"], "alternates": {"html": "https://wpnews.pro/news/i-ported-a-knowledge-format-okf-library-to-zero-dependency-net-here-s-what-i", "markdown": "https://wpnews.pro/news/i-ported-a-knowledge-format-okf-library-to-zero-dependency-net-here-s-what-i.md", "text": "https://wpnews.pro/news/i-ported-a-knowledge-format-okf-library-to-zero-dependency-net-here-s-what-i.txt", "jsonld": "https://wpnews.pro/news/i-ported-a-knowledge-format-okf-library-to-zero-dependency-net-here-s-what-i.jsonld"}}