Hyperon-MCP (atomspace-agent)

An MCP server that gives coding agents (Claude Code, Codex, OpenClaw, OmegaClaw) persistent, scoped symbolic memory with real PLN/NAL inference on the OpenCog Hyperon MeTTa stack:

• one global AtomSpace — cross-project preferences and learned rules,

• one AtomSpace per repo — architecture facts, dependency edges, invariants, decisions — keyed by normalized git remote (clones/worktrees share a space),

• inference by the vendored, frozen lib_nal.metta / lib_pln.metta from OmegaClaw-Core (@ dbb22b0), evaluated on the hyperon runtime (PeTTa subprocess backend optional),

• truth values everywhere: atoms carry (stv f c); multi-hop conclusions decay in confidence, contradictions merge by NAL revision, provenance follows OmegaClaw's memory_schema contract (tool_result 0.9 / user 0.8 / knowledge_prior 0.7 / llm 0.55).

Install & run

pip install -e '.[full]'      # hyperon + mcp
atomspace-agent               # stdio MCP server
atomspace-agent selftest      # end-to-end smoke: assert -> query -> 2-hop infer -> export

Claude Code: drop skills/claude-code/.mcp.json into your project (or merge it) and install the skills/claude-code/atomspace skill. Codex: see skills/codex/AGENTS.snippet.md. OpenClaw: skills/openclaw/atomspace. OmegaClaw: point profile/plugins.yaml roots at plugins/omegaclaw-bridge (no MCP needed — it bridges through plugin_registry).

Tools (11)

atom_assert · atom_assert_batch · atom_query (pattern match, $-vars) · infer (k-hop PLN/NAL with proof traces, subprocess + hard timeout) · revise (NAL revision) · atom_retract (supersede, never delete) · scope_info (counts, contradictions) · hybrid_recall · bootstrap_project (import-scan → (Implication (affected file:dep) (affected file:dependent)) edges + doc topics; writes committable .atomspace/seed.metta) · snapshot_export · snapshot_import.

Atom schema (LLM-learnable: 5 shapes, 6 prefixes)

Inheritance (taxonomy) · Implication (impact edges/invariants) · Similarity · Evaluation (conventions/decisions/preferences) · Not — over namespaced terms file: module: dir: dep: decision: user:. See skills/SKILL_BODY.md for the full discipline (assert budget, stv reading, counter-examples).

Safety

Atoms are parsed to an AST, never string-eval'd (validate.py): closed head whitelist, closed symbol charset, banned grounded-op tokens, depth/size caps. Validated atoms hydrate into MeTTa as premise data inside (|-nal ...)/(|~pln ...) calls — never as (= ...) equations. Inference runs in a worker subprocess with a hard wall-clock timeout.

Benchmarks

Benchmark-gated development lives in OmegaClaw-Bench under benchmarks/atomspace/ (gates pre-registered in benchmark-docs/atomspace.md): T0 engine/store/MCP conformance → T1 retrieval quality → T2 multi-hop decision-change (the primary program gate) → T3 end-to-end agent outcomes.

python -m pytest tests/          # unit + cross-backend conformance

Layout

src/atomspace_agent/   server, store, scopes, validate, runtime, inference,
                       revision, bridge, bootstrap, export, truth, conformance
src/atomspace_agent/metta/   vendored lib_nal / lib_pln + lib_compat shims
skills/                canonical SKILL_BODY.md + per-host packs
plugins/omegaclaw-bridge/    OmegaClaw plugin_registry bridge (4 tools)
tests/                 unit tests + T0.1 golden conformance