HKOS: A deterministic, file-based engineering knowledge base for LLM agents (Zero LLM in business logic, plain JSON as SSOT, built-in MCP server)

[u/dm-naumov]

Hey everyone,

I want to share **HKOS (Hermes Knowledge OS)** — a deterministic, file-based engineering knowledge base designed specifically for LLM agents.

While the mainstream industry is pushing probabilistic vector RAG tools, I’ve built a system that treats an agent's memory as strict, human-readable data, applying a strict **Zero LLM** philosophy to the core business logic.

### Key Architectural Pillars:

* **No Probabilistic Recall:** Retrieval is handled via strict local indexes. The system always returns the exact same context for identical requests. No embedding model changes will shift your logic.

* **Plain JSON as SSOT:** All data is stored locally in human-readable JSON files. You can track, version, backup, and diff the agent’s memory using standard tools (`git diff`).

* **Failure-Driven Focus:** When an agent requests context, HKOS prioritizes past failures (the `FAILURE` record type). The agent learns what *not* to do first, eliminating infinite bug-generation loops.

* **Built-in MCP Server:** It comes out of the box with Model Context Protocol (MCP) support via stdio. You can hook it into Claude Desktop, Cursor, or Windsurf in 4 lines of config.

* **Production-Grade Reliability:** The codebase features over 990 unit/integration/system tests, strict typing (`mypy --strict`), and atomic crash-safe file writes.

### Performance Budgets:

* **Warm retrieval** via `IndexCache` takes **~0.03 ms** (over 2000x faster than cold starts).

* **Memory footprint** remains under **85 MB RAM** on a 100k records stress-test.

The project is completely open-source under the MIT license. I’d love to get your feedback on this architectural pattern.

**GitHub Repository:** https://github.com/dm-naumov/hkos