Project status: pre-1.0, active development — APIs, schema, and layout may change between
0.x releases. Pinned to a specific Hermes-Agent version (see engine-manifest.yaml).
Cost warning: OKEngine is designed to run autonomous agents on a schedule.
With empty feeds it is almost free, but once you add active sources it can make
continuous LLM calls. A busy pack can cost real money. Read
docs/operating-cost.md and set provider-side hard
caps before enabling ingest crons.
OKEngine (short for Open Knowledge Engine) turns an agent into a wiki maintainer. It
watches sources, writes structured markdown pages, links them together, repairs drift, and keeps
the wiki useful over time. Swap the domain pack and the same engine can maintain a security
wiki, an investor wiki, a legal wiki, a research wiki, or a product-intelligence wiki.
a live deployment today = OKEngine @ a pinned Hermes + one pack **or bundle**
The catalyst was Andrej Karpathy's
LLM-wiki pattern:
an agent should accumulate knowledge in a durable wiki instead of rediscovering
it from scratch on every query. OKF compatibility is the small portability floor
(type in YAML frontmatter); OKEngine's core is the swappable-topic LLM-wiki
engine.
New here? Start with docs/overview.md.
A raw article:
Acme Security acquires LogLens to add cloud detection telemetry.
The pack decides what that means and writes a typed page:
---
type: vendor
title: Acme Security
sources:
- "[[sources/2026/06/acme-acquires-loglens]]"
updated: 2026-06-21
---
# Acme Security
Acme Security is expanding from endpoint detection into cloud telemetry through
the LogLens acquisition.
## Strategic read
The deal suggests Acme is repositioning against cloud-native detection vendors.
The engine then handles the generic work: validate the write, update indexes,
refresh hot sets, maintain backlinks, expose reader/MCP/search surfaces, and run
repair drains if the page drifts.
Most "chat with your docs" systems answer a question and forget the work. OKEngine
uses an agent plus a wiki instead:
- Sources are compiled once into reusable pages.
- Entities, concepts, predictions, and sources are cross-linked.
- Claims and predictions can be revisited and graded.
- Maintenance jobs keep the corpus healthy.
- Search loads already-synthesized knowledge, not just raw chunks.
RAG can still be a retrieval technique. It is not the memory layer. The wiki is
the memory.
The engine ships zero domain knowledge. A pack supplies the domain:
schema.yaml, persona, feeds, prompts, crons, optional seed content, and runtime
configuration.
A pack deploys standalone, or several compose into one vault: kind: bundle
recipes and framework install-domain merge packs with disjoint type/namespace
ownership behind a coinstall preflight (framework compose-preview shows the merged
shape first).
- Enforced write path:
okengine-mcp/write_server.py validates agent writes,
guards against field loss, blocks reserved files, tombstones instead of deleting,
and logs writes.
- Self-maintaining corpus: cron jobs refresh indexes, hot sets, tiers,
wikilinks, schema health, source freshness, and repair queues.
- Reader:
okengine-reader/ is a read-only web UI for the wiki.
- MCP query surface:
okengine-mcp/ exposes read-only tools such as search,
page fetch, references, and page listing.
- Framework CLI:
bin/framework manages pack lifecycle and discovers, plans,
executes, resumes, cancels, and inspects durable operations contributed by packs/extensions.
python scripts/framework.py remains supported for invocation compatibility.
See the supported operator CLI for the public command and internal-tool
boundary.
Scheduled jobs are managed by stable name with bin/framework jobs; cron-plus hashes are
intentionally kept internal.
Deterministic checks and canonical fixes use the receipted, plan-before-mutation
framework audit / framework repair workflow.
Declarative ingestion and disposable artifact regeneration use the bounded
framework ingest, sources, and rebuild commands.
Read-only provenance explanations and bounded analytical evidence artifacts use
framework explain, snapshot, and export.
- OKF-compatible floor: markdown + YAML pages with the minimal
type field
baseline where conformance is enabled.
-
Clone the engine
git clone <engine-repo> okengine
No manual Hermes/patch/overlay work needed — deploy.sh (step 3) builds the hermes-agent
Docker image (pinned Hermes + patches/ + overlay) on first run. The deployable
docker-compose.yml ships with the pack (step 2), not the engine. See
INSTALL.md for the build internals / by-hand path.
-
Get a domain pack
Use a catalog pack:
bin/framework list
bin/framework pull <pack> ../my-brain
Or scaffold a new one:
bin/framework init ../my-brain --domain "..."
bin/framework validate ../my-brain
The engine checkout and vault are separate sibling directories:
okengine/ + my-brain/.
-
Deploy from the vault directory
bash ../okengine/scripts/deploy.sh
OKEngine is a 24/7 autonomous agent system. With an empty feed list, ingest
crons are wake-gated and the LLM rarely fires. Once you populate feeds, it can make
LLM API calls continuously. Cost depends on feed volume, prompts, model choice,
and retry behavior.
Controls:
- Use a local/free model where possible.
- Set hard spend caps with your model provider.
- Enable the
budget-guard cron.
- Read
docs/operating-cost.md before adding feeds.
docs/executive-guide.md — executive system guide:
product model, architecture, concepts, governance, and the current pack map.docs/overview.md — start here: concept, packs, and
architecture.docs/operating-cost.md — token/cost model and budget
controls.INSTALL.md — install OKEngine on pinned Hermes.docs/install-selected-pack.md — install an
existing pack.docs/install-okpack-cti.md — install the
security/threat-intel pack.docs/install-okpack-ai-research.md —
install the AI/LLM research-watch pack.docs/authoring-a-pack.md — author a new pack.docs/source-connectors.md — declarative Bundle,
Query, Enrichment, and Stream/Poll source acquisition.docs/deploy-a-new-domain.md — pack spec and
deployment guide.docs/engine-domain-boundary.md — engine vs
pack boundary.docs/okf/okengine-conformance-spec.md
— OKEngine conformance profile and OKF compatibility floor.docs/okf/ — LLM-wiki guides: pattern, vault building,
integrations, and scaling.engine-manifest.yaml — engine-layer file list and
pinned dependencies.
Runtime dependencies are cloned separately and pinned in
engine-manifest.yaml:
- Hermes-Agent — the agent
runtime. OKEngine consumes it as a pinned dependency and carries a small patch
set under
patches/.
- cron-plus — subprocess-per-job
scheduler for the cron fleet.
Apache-2.0 — see LICENSE. Carried patches under patches/ are diffs
against Hermes; Hermes' own license governs Hermes code.