akh-medu

A neuro-symbolic AI engine made to run on the CPU. Made for people. Not for robber barons.

Documentation

For per-akh OpenAI API, Codex and Claude agent sessions, see coding-agent backends.

akh-medu combines hyperdimensional computing (Vector Symbolic Architecture) with knowledge graphs and symbolic reasoning. It runs entirely on the CPU with no LLM dependency, no GPU requirement, and no external NLP models.

• Infer new knowledge via spreading activation, backward chaining, and superposition reasoning
• Reason symbolically using e-graph rewrite rules (equality saturation)
• Search semantically using 10,000-bit binary hypervectors
• Act autonomously via an OODA-loop agent with 15 built-in tools
• Parse and generate natural language in 5 languages via a grammar framework
• Serve knowledge over REST and WebSocket APIs

Quick Start

cargo build --release
akh-medu init
akh-medu seed apply ontology
akh-medu grammar parse "Dogs are mammals" --ingest
akh-medu query --seeds Dog --depth 2

See the Quick Start Tutorial for a full walkthrough.

Architecture

┌──────────────────────────────────────────────────────────┐
│                      Engine API                          │
├──────────┬──────────┬──────────┬──────────┬──────────────┤
│   VSA    │Knowledge │Reasoning │Inference │   Agent      │
│  Ops     │  Graph   │  (egg)   │ Engine   │  OODA Loop   │
│ ─────────│──────────│──────────│──────────│──────────────│
│ HyperVec │petgraph  │ rewrite  │spreading │ 15 tools     │
│ SIMD     │oxigraph  │ rules    │backward  │ planning     │
│ ItemMem  │SPARQL    │ e-graphs │superpos. │ psyche       │
├──────────┴──────────┴──────────┴──────────┴──────────────┤
│                   Tiered Storage                         │
│  Hot (DashMap) · Warm (mmap) · Durable (redb)            │
└──────────────────────────────────────────────────────────┘

The rest of the workspace

The engine is the root crate. Around it:

Crate	Role
seshat	Shared corpus library — RAG over pgvector
heka	Postgres+pgvector evaluation store for long-term memory
akhomed-store	Postgres-backed durable store for relocatable Akhs
anima-ai	Multi-engine natural-language routing
grug-data / grug-train	Grug-Brain BabyLLM data generation and Burn training beachhead
akh-egraph-bench	E-graph reasoning microbenchmarks
benchmarks/harness-core	The agentic-task benchmark harness (below)

Deployment: a Helm chart in charts/akh-medu, Linux and illumos packaging in packaging/, and cargo binstall support that pulls prebuilt akh binaries from the Forgejo releases rather than compiling.

Benchmarks

benchmarks/ is a reproducible harness for agentic tasks, not a marketing table. Each run is pinned to a task-set hash and a harness SHA; once a task-set hash has a published run against it, that hash is frozen — edits land under a new hash rather than silently changing what an earlier row measured. benchmarks/LEADERBOARD.md is generated by bench-tool leaderboard from the committed runs under benchmarks/results/, never edited by hand.

The harnesses include illumos-e2e and illumos-orchestration — real operating-system maintenance and fleet-orchestration tasks, graded autonomously on a VM — alongside frontiercode, locomo and longmemeval. Published pass rates run from 100% on fleet-orchestration down to 0% on frontiercode. They are recorded as measured.

Documentation

The full documentation is hosted at akh-medu.dev and covers:

• Installation -- build from source, feature flags
• Quick Start Tutorial -- first engine, symbols, queries, agent
• Concepts -- VSA, knowledge graphs, inference, reasoning
• Agent -- OODA loop, tools, planning, Jungian psyche
• Server -- REST and WebSocket APIs
• CLI Reference -- all commands and options

To build the docs locally:

cd book && mdbook serve

License

This repository is licensed under GPL-3.0-only. See the LICENSE file.

For integration into proprietary applications, contact the author — commercial licences are sold deliberately, and the money funds the FLOSS work.

Contributing

Contributions are welcome under the arrangement that pays for this project: contributors agree that their contribution may also be offered under a paid proprietary licence alongside the GPL. That is what lets proprietary vendors fund FLOSS work instead of free-riding on it. Open the discussion before a large change so nobody wastes an evening.

Dependencies and IP boundaries

• The engine ships no model weights and requires none. No LLM dependency, no GPU, no external NLP models — VSA operations, the knowledge graph, e-graph reasoning and the grammar framework are all implemented in this repository and run on the CPU.
• All third-party dependencies are unmodified upstream crates from crates.io under their own licences, pinned by Cargo.lock. Notable ones are egg (e-graphs), oxigraph (RDF/SPARQL), petgraph, redb, dashmap and burn.
• No proprietary code or datasets are included, and no training corpus is committed. data/ holds hand-authored seed ontologies, compartment definitions and a schema.org schema pack; training/ holds run configs and scripts only. Training data is generated by grug-data in this repository.
• Optional external services are the operator's own: PostgreSQL with pgvector for seshat and heka, and any cloud model endpoint a benchmark harness is pointed at. akh-medu holds no credentials of its own and phones nothing home.
• Everything an operator puts in — symbols, triples, corpora, benchmark runs — stays the operator's.