HKOS — Hermes Knowledge OS

A deterministic, file-based engineering knowledge base for LLM agents.

HKOS is a long-lived, object-oriented knowledge database designed to store and structure engineering memory independently of any LLM. Knowledge is written through a single canonical path, indexed locally, retrieved with a bounded query contract, and snapshotted — all in plain JSON files, with no daemon, no external services, and no embeddings.

Deterministic by design. The classification, indexing, retrieval and lifecycle logic contains zero LLM calls. Your memory survives model swaps, prompt changes and vendor lock-in — the knowledge base is the source of truth, not the model.

Why HKOS exists

LLM agent memory solutions today are typically LLM-dependent: embeddings, model-generated "memories", and vector stores that only mean something to the model that produced them. That design has a hard ceiling:

• memory quality silently changes when you swap the model;
• vector recall is probabilistic — the same query can return different results;
• there is no auditable, human-readable source of truth;
• failure modes are opaque and hard to debug.

HKOS takes the opposite position: memory is engineering data. It is written deliberately, validated, versioned, and stored as plain JSON under a single source of truth (SSOT). Retrieval is deterministic, explainable, and fast enough for interactive agent use. This is what a production engineering organization needs — not a black box.

Architecture

                        ┌───────────────────────────────────────────┐
                        │ integration/   Hermes Agent adapters       │
                        │ migration/     schema migration FSM,       │
                        │                backup / rollback           │
                        └──────────────────────┬────────────────────┘
                                               ▼
                        ┌───────────────────────────────────────────┐
                        │ services/  Project · Campaign (FSM) ·      │
                        │            Librarian · MemoryService       │
                        └──────────────────────┬────────────────────┘
              ┌────────────────────────────────┼────────────────────────────────┐
              ▼                                ▼                                ▼
       retrieval/                       context/                        snapshot/
       deterministic ranking           context builder                 derived state,
       with explanations               (profiles, budgets)            versioned & diffed
              └────────────────────────────────┼────────────────────────────────┘
                                               ▼
                        ┌───────────────────────────────────────────┐
                        │ index/    5 indexes, Query Contract Q1–Q5, │
                        │           IndexCache (warm ≈ O(1))         │
                        └──────────────────────┬────────────────────┘
                                               ▼
                        ┌───────────────────────────────────────────┐
                        │ repository/  JSON Repository — the ONLY    │
                        │              source of truth (SSOT)        │
                        └──────────────────────┬────────────────────┘
                                               ▼
                        ┌───────────────────────────────────────────┐
                        │ storage/   StorageEngine, JSONStore,       │
                        │            HKOS-08 envelopes               │
                        └──────────────────────┬────────────────────┘
                                               ▼
                        ┌───────────────────────────────────────────┐
                        │ core/ · kernel/ · performance/             │
                        │ engine, config, logging · shared types ·   │
                        │ metrics & profiling (zero business logic)  │
                        └───────────────────────────────────────────┘

Dependencies flow strictly downward. services/ orchestrates; migration/ is a maintenance layer on top; performance/ measures but never mutates.

Design invariants

1. Repository is the single source of truth. Indexes, snapshots, manifests and caches are derived projections — always rebuildable from the repository, never authoritative.
2. The Librarian is the only write path for knowledge. register → validate → canonicalize — no other component may create or mutate knowledge.
3. Deterministic classification. Categories (FACT, DECISION, FAILURE, CONFIGURATION, RULE, …) are assigned by a rule-based classifier — no LLM in the pipeline.
4. Crash-safe writes. All storage writes are atomic (tmp + rename). kill -9 mid-write leaves either the old or the new record — never a partial one. Recovery is rebuild, not repair.
5. Schema evolution is a first-class operation. A migration FSM (backup → apply → rebuild index → regenerate snapshot → validate) with an append-only event log and idempotent rollback.
6. No daemon, no global state, no hidden databases. HKOS is a library; everything is files and injected dependencies (constructor DI).

Knowledge lifecycle

register ──► NEW ──► VERIFIED ──► CANONICAL ──► ARCHIVED
                │        │
                └────────┴──► REJECTED / SUPERSEDED

• NEW — just registered, not yet part of retrievable memory;
• VERIFIED — passed validation;
• CANONICAL — the only status visible to retrieval (reusable);
• ARCHIVED / REJECTED / SUPERSEDED — filtered out of retrieval; negative knowledge (FAILURE with cause/fix) is kept and resurfaces first when the same mistake is about to be repeated.

Quick start

pip install hkos          # Python 3.12+
# or, from a checkout:  uv venv .venv && uv pip install -e .

# examples/quickstart.py — full pipeline on a throwaway corpus
from hkos.core.config import ConfigLoader
from hkos.core.logger import HKOSLogger
from hkos.core.version import VersionManager
from hkos.storage import StorageEngine
from hkos.repository.repository_manager import RepositoryManager
from hkos.repository.models import Knowledge
from hkos.services.project_manager import ProjectManager
from hkos.services.campaign_manager import CampaignManager
from hkos.services.librarian import Librarian
from hkos.index import IndexEngine, IndexStore, IndexCache, IndexQueryExecutor
from hkos.retrieval import RetrievalEngine

cfg = ConfigLoader().load()
engine = StorageEngine(root="./hkos", config=cfg,
                       logger=HKOSLogger(), version=VersionManager())
engine.initialize()
repos = RepositoryManager(engine)

project = ProjectManager(repos, HKOSLogger()).create(
    name="Demo", description="quickstart", tags=["demo"])
Librarian(repos, HKOSLogger()).register(project.id, Knowledge(
    title="TCP redirect works via nftables",
    body="meta l4proto tcp redirect to :12345", tags=["tcp", "nftables"]))

index = IndexEngine(repos, IndexStore(engine), HKOSLogger(), cache=IndexCache())
index.build(project.id)
retrieval = RetrievalEngine(repos, IndexQueryExecutor(IndexStore(engine), cache=IndexCache()),
                            cfg, HKOSLogger())
print(retrieval.retrieve("tcp redirect", project_id=project.id))

Real output of python examples/quickstart.py:

data root: /tmp/hkos-demo-x9wwf6se
project: 8c1bbd63-96ca-4c72-bd34-b70cae72bcc4
campaign: 9f00ff23-87d6-4ae5-a501-91406d50e72b
knowledge registered & canonicalized: 3
retrieval: 1 item(s) for 'udp proxy'
  [FAILURE] UDP traffic bypasses the proxy
snapshot: snapshot-00001 knowledge=3
OK

Note how the negative knowledge (the FAILURE entry) is what the retriever returns for a query about a problem — that is HKOS's core value: past mistakes are reused before they are repeated.

Performance

Measured on a stock Linux workstation, corpus generated deterministically (no LLM involvement). Full methodology and reproduction scripts in release/BENCHMARKS.md.

Quality

• 990+ tests — 807 unit, 112 integration, 51+ system-level scenarios (pipeline, lifecycle, 10K growth, consistency, failure recovery, concurrent agents, migration, security, 100K stress, long-running, operational).
• mypy --strict: 0 errors across 272 files.
• ruff: 0 functional findings (docstring style only).
• compileall: clean.
• All layers tested at unit + integration level; system tests exercise only public APIs (SSOT discipline is itself enforced by tests).

How is this different?

In one sentence: most agent-memory tools make memory another model's output; HKOS makes memory your engineering data — deterministic, versioned, auditable, and portable across LLMs.

MCP

HKOS ships an MCP server (hkos-mcp, stdio, zero dependencies): any MCP client — Claude Desktop, IDEs, agent frameworks — can retrieve, context, save, snapshot, doctor and status against an HKOS knowledge base.

pip install hkos
hkos-mcp --root ./hkos        # data root (HKOS_DATA_ROOT / HKOS_PROFILE env)

// claude_desktop_config.json
{ "mcpServers": { "hkos": { "command": "hkos-mcp",
                            "args": ["--root", "/abs/path/data-root"] } } }

See docs/mcp.md for the tool reference and client setup.

Documentation

• Installation
• Architecture
• API reference
• Developer guide
• Performance guide
• Migration guide
• Troubleshooting
• Administrator guide

Roadmap

• v1.0 — current: core, storage, repository, index, retrieval, context, snapshot, services, migration, integration, performance layers.
• v1.1 — MCP adapter (stdio server for any MCP client), semantic search as an optional backend (SSOT untouched), CLI package.
• v1.2 — SQLite storage backend (same API, envelope format preserved), cross-project knowledge graphs.

License

MIT — see LICENSE.

HKOS was developed in 15 certified sprints (DS-001…DS-015) with a documented engineering process: architecture reviews, adversarial audits, performance budgets, and system-level qualification. Design decisions are documented in docs/design/.