# 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](https://github.com/asi-alliance/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

```bash
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](../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.

```bash
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
```