# Aeonora Brain Adapter v1

Status: open interface plus four Markdown/context adapters. Database-native and provider API adapters remain future work.

## Purpose

Aeonora must move an agent without choosing its memory engine. GBrain, llm-wiki, a Markdown directory, a database, or another MCP memory service can participate when an adapter can produce and restore the same encrypted state commitment.

## Required Surface

```text
describe() -> provider metadata + capabilities
snapshot() -> deterministic private export
commit(snapshot) -> bytes32 commitment
restore(snapshot, grant) -> provider state
query(request, grant) -> scoped answer
grant(runtime, scope, expiry) -> wrapped access grant
revoke(grant) -> revocation receipt
```

## Portability Contract

An adapter passes only when it can:

1. export a deterministic snapshot without plaintext leaving the trusted boundary;
2. encrypt before remote or content-addressed storage;
3. reproduce the manifest `brain.commitment` from encrypted bytes;
4. restore into a clean provider instance;
5. answer a fixed verification query equivalently before and after restore;
6. issue a runtime-scoped, expiring key grant;
7. deny reads after revocation;
8. disconnect without changing the canonical agent ID.

Equivalent answers do not require byte-identical database internals. The adapter MUST define which state is canonical and which indexes or caches may be rebuilt.

## Provider Profiles

- `gbrain`: export canonical pages, schema-pack identity, source configuration without credentials, and required graph state; rebuild disposable indexes when safe.
- `llm-wiki`: export canonical wiki pages, link graph, metadata, and schema version.
- `filesystem`: export a normalized file tree with paths, modes, and content; exclude secrets and runtime caches.
- `mcp`: use a provider-specific export endpoint plus the common restore and verification contract.

Provider profiles are adapters. None is required by Aeonora core.

## Shipped harness adapters

`aeonora-adapter` captures and reconnects documented Markdown/context surfaces for:

- Hermes: `memories/`, `skills/`, `MEMORY.md`, `USER.md`, `SOUL.md`, and context files;
- OpenClaw: workspace identity, memory, and skill Markdown;
- NanoClaw v2: `groups/**/*.md`, provider-neutral `memory/`, skills, and persistent `instructions.prepend.md` bootstrap instructions;
- OpenHands: `AGENTS.md` and current/legacy skill directories.

Install writes the portable brain under `.aeonora/brain/` and adds one idempotent bootstrap instruction to the harness context file. Credentials, OAuth state, proprietary session databases, and model keys are deliberately excluded.

Use `auto` to detect the installed Hermes or OpenClaw Markdown root:

```bash
aeonora-adapter capture hermes auto .aeonora/hermes
aeonora-adapter capture openclaw auto .aeonora/openclaw
```

NanoClaw and OpenHands default to the current project when `auto` is used. Override discovery with `HERMES_HOME`, `OPENCLAW_WORKSPACE`, `NANOCLAW_HOME`, or `OPENHANDS_WORKSPACE`.

## Security Boundary

The chain receives the encrypted snapshot commitment, never the snapshot, plaintext memory, bearer token, database credentials, or private key. Controller keys, brain root keys, and runtime grant keys remain distinct.