hkos 1.0.0__tar.gz

hkos-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Naumov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hkos-1.0.0/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: hkos
+Version: 1.0.0
+Summary: Deterministic, file-based engineering knowledge base for LLM agents (SSOT, retrieval, snapshots, migrations)
+Author-email: Dmitry Naumov <hkos_dmitry@proton.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dm-naumov/hkos
+Project-URL: Documentation, https://github.com/dm-naumov/hkos#readme
+Project-URL: Source, https://github.com/dm-naumov/hkos
+Keywords: knowledge-base,llm-agents,agent-memory,retrieval,engineering-knowledge,deterministic,ssot,python
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-rerunfailures>=14.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mcp>=1.0; extra == "dev"
+Dynamic: license-file
+
+# HKOS — Hermes Knowledge OS
+
+[![CI](https://github.com/dm-naumov/hkos/actions/workflows/ci.yml/badge.svg)](https://github.com/dm-naumov/hkos/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)]()
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-990%2B-brightgreen.svg)]()
+[![mypy](https://img.shields.io/badge/mypy-strict-2ea44f.svg)]()
+[![ruff](https://img.shields.io/badge/ruff-0%20functional%20findings-2ea44f.svg)]()
+
+**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
+
+```bash
+pip install hkos          # Python 3.12+
+# or, from a checkout:  uv venv .venv && uv pip install -e .
+```
+
+```python
+# 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`](release/BENCHMARKS.md).
+
+| Operation | Budget (SLA) | Measured |
+|---|---|---|
+| Retrieval, cold (10K knowledge) | < 100 ms | PASS |
+| Retrieval, warm (IndexCache) | — | ~0.03 ms (2120× faster than cold) |
+| Context build (10K) | < 200 ms | PASS |
+| Save (register → canonicalize) | < 150 ms | PASS |
+| Snapshot load / create / diff | < 50 / < 300 / < 500 ms | PASS |
+| Migration detect @100K | < 100 ms | < 25 ms (VersionManifest; was 1470 ms) |
+| Migration backup / rollback / validate | < 5 / < 10 / < 10 s | 2.8 / 3.2 / 7.2 s |
+| Index build 30K | linear | 1.5 s (was 84.6 s — O(N²) removed) |
+| 100K knowledge, full corpus | — | generate 19.4 s · RAM 85 MB · retrieval < 100 ms |
+| 1M stress | — | mechanism validated (200K in-session); full run via `HKOS_STRESS_SCALE=1000000` |
+| Crash safety | — | `kill -9` mid-write: zero partial records (atomic tmp+rename) |
+
+## 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?
+
+| | HKOS | Mem0 / basic-memory | Vector-store agent memory |
+|---|---|---|---|
+| Memory source of truth | JSON repository (files) | internal store, LLM-extracted | embeddings (model-dependent) |
+| Determinism | yes — same query, same result | no — model-dependent | no — approximate |
+| LLM needed to *read* memory | no | no | yes (embedding model) |
+| LLM needed to *write* memory | no (rule-based classifier) | yes (extraction prompt) | yes |
+| Auditable / diffable | yes (plain JSON, snapshots, diff) | limited | no |
+| Schema migration | first-class FSM + rollback | — | — |
+| Crash-safe | atomic writes, `kill -9`-proof | — | — |
+| Explains why an item was retrieved | yes (reason/score per item) | no | no |
+
+**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.
+
+```bash
+pip install hkos
+hkos-mcp --root ./hkos        # data root (HKOS_DATA_ROOT / HKOS_PROFILE env)
+```
+
+```json
+// claude_desktop_config.json
+{ "mcpServers": { "hkos": { "command": "hkos-mcp",
+                            "args": ["--root", "/abs/path/data-root"] } } }
+```
+
+See [docs/mcp.md](docs/mcp.md) for the tool reference and client setup.
+
+## Documentation
+
+- [Installation](docs/installation.md)
+- [Architecture](docs/architecture.md)
+- [API reference](docs/api-reference.md)
+- [Developer guide](docs/developer.md)
+- [Performance guide](docs/performance-guide.md)
+- [Migration guide](docs/migration-guide.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Administrator guide](docs/administrator.md)
+
+## 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](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/`](docs/design/).*

hkos-1.0.0/README.md

@@ -0,0 +1,275 @@
+# HKOS — Hermes Knowledge OS
+
+[![CI](https://github.com/dm-naumov/hkos/actions/workflows/ci.yml/badge.svg)](https://github.com/dm-naumov/hkos/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)]()
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-990%2B-brightgreen.svg)]()
+[![mypy](https://img.shields.io/badge/mypy-strict-2ea44f.svg)]()
+[![ruff](https://img.shields.io/badge/ruff-0%20functional%20findings-2ea44f.svg)]()
+
+**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
+
+```bash
+pip install hkos          # Python 3.12+
+# or, from a checkout:  uv venv .venv && uv pip install -e .
+```
+
+```python
+# 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`](release/BENCHMARKS.md).
+
+| Operation | Budget (SLA) | Measured |
+|---|---|---|
+| Retrieval, cold (10K knowledge) | < 100 ms | PASS |
+| Retrieval, warm (IndexCache) | — | ~0.03 ms (2120× faster than cold) |
+| Context build (10K) | < 200 ms | PASS |
+| Save (register → canonicalize) | < 150 ms | PASS |
+| Snapshot load / create / diff | < 50 / < 300 / < 500 ms | PASS |
+| Migration detect @100K | < 100 ms | < 25 ms (VersionManifest; was 1470 ms) |
+| Migration backup / rollback / validate | < 5 / < 10 / < 10 s | 2.8 / 3.2 / 7.2 s |
+| Index build 30K | linear | 1.5 s (was 84.6 s — O(N²) removed) |
+| 100K knowledge, full corpus | — | generate 19.4 s · RAM 85 MB · retrieval < 100 ms |
+| 1M stress | — | mechanism validated (200K in-session); full run via `HKOS_STRESS_SCALE=1000000` |
+| Crash safety | — | `kill -9` mid-write: zero partial records (atomic tmp+rename) |
+
+## 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?
+
+| | HKOS | Mem0 / basic-memory | Vector-store agent memory |
+|---|---|---|---|
+| Memory source of truth | JSON repository (files) | internal store, LLM-extracted | embeddings (model-dependent) |
+| Determinism | yes — same query, same result | no — model-dependent | no — approximate |
+| LLM needed to *read* memory | no | no | yes (embedding model) |
+| LLM needed to *write* memory | no (rule-based classifier) | yes (extraction prompt) | yes |
+| Auditable / diffable | yes (plain JSON, snapshots, diff) | limited | no |
+| Schema migration | first-class FSM + rollback | — | — |
+| Crash-safe | atomic writes, `kill -9`-proof | — | — |
+| Explains why an item was retrieved | yes (reason/score per item) | no | no |
+
+**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.
+
+```bash
+pip install hkos
+hkos-mcp --root ./hkos        # data root (HKOS_DATA_ROOT / HKOS_PROFILE env)
+```
+
+```json
+// claude_desktop_config.json
+{ "mcpServers": { "hkos": { "command": "hkos-mcp",
+                            "args": ["--root", "/abs/path/data-root"] } } }
+```
+
+See [docs/mcp.md](docs/mcp.md) for the tool reference and client setup.
+
+## Documentation
+
+- [Installation](docs/installation.md)
+- [Architecture](docs/architecture.md)
+- [API reference](docs/api-reference.md)
+- [Developer guide](docs/developer.md)
+- [Performance guide](docs/performance-guide.md)
+- [Migration guide](docs/migration-guide.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Administrator guide](docs/administrator.md)
+
+## 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](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/`](docs/design/).*

hkos-1.0.0/__init__.py

@@ -0,0 +1,37 @@
+"""Hermes Knowledge OS (HKOS)
+============================
+An object-oriented file-based engineering knowledge database.
+
+DS-001 (Sprint 1): Foundation
+- HKOS as an importable module
+- Bootstrap, Configuration, Logger, Registry
+- Version and Health management
+"""
+
+from hkos.core.config import ConfigLoader
+from hkos.core.exceptions import (
+    ConfigurationError,
+    HKOSError,
+    InitializationError,
+    RuntimeErrorHKOS,
+    ValidationError,
+)
+from hkos.core.health import HealthManager
+from hkos.core.hkos import HKOS
+from hkos.core.logger import HKOSLogger
+from hkos.core.registry import Registry
+from hkos.core.version import VersionManager
+
+__all__ = [
+    "HKOS",
+    "VersionManager",
+    "ConfigLoader",
+    "HealthManager",
+    "Registry",
+    "HKOSLogger",
+    "HKOSError",
+    "ConfigurationError",
+    "InitializationError",
+    "RuntimeErrorHKOS",
+    "ValidationError",
+]