# Aionis

> Aionis is an execution memory runtime for AI agents. It turns plans, decisions, validation results, handoffs, feedback, and invalidated alternatives into governed state for the next agent context.

## Canonical URLs

- Website: https://www.aionis.work/
- Interactive demo: https://www.aionis.work/demo/
- Plugins: https://www.aionis.work/plugins/
- Research: https://www.aionis.work/research/
- Documentation: https://docs.aionis.work/
- GitHub: https://github.com/ostinatocc/Aionis
- Runtime release: https://github.com/ostinatocc/Aionis/releases/tag/v0.3.2
- Docker image: ghcr.io/ostinatocc/aionis:v0.3.2
- npm installer: https://www.npmjs.com/package/@aionis/create
- npm SDK: https://www.npmjs.com/package/@aionis/sdk
- npm MCP bridge: https://www.npmjs.com/package/@aionis/mcp
- Claude Code plugin: https://github.com/ostinatocc/aionis-claude-code

## Core product surfaces

- Runtime-first setup: `npx aionis setup` installs the local Runtime, writes `.env`, and lets SDK/API/MCP/AIFS/native plugins connect afterward.
- Memory Firewall: admits memory into use_now, inspect_before_use, do_not_use, or rehydrate before it reaches an AI agent prompt.
- Agent Flight Recorder: records what memory the agent could see, what was blocked, why it was surfaced, and what outcome followed.
- State-Preserving Context Compression: compresses long execution history while preserving current state, blocked or invalidated alternatives, procedure memory, audit receipts, and rehydrate pointers.
- Candidate Retrieval Engine: uses optional local ANN, lexical, structured, graph, and recent sources to generate candidates while Aionis keeps admission governance separate.
- Native Plugins: installs Aionis into agent tools with lifecycle hooks. Claude Code is available today; Codex, OpenClaw, and Hermes Agent plugin paths are planned.

## Research notes

- Execution memory is not chat history: https://www.aionis.work/research/execution-memory-runtime/
- Memory Firewall: admission before influence: https://www.aionis.work/research/memory-firewall/
- Strong retrieval below. Strict governance above: https://www.aionis.work/research/candidate-retrieval-engine/
- State-preserving context compression: https://www.aionis.work/research/state-preserving-context-compression/
- The admission policy flywheel: https://www.aionis.work/research/admission-policy-flywheel/

## Benchmark evidence

- MGBench v0.1.1: 608 deterministic memory-governance scenarios, archived at DOI 10.5281/zenodo.20793097.
- MGBench strict ID-neutral Zvec ANN rerun: Aionis observe->guide recovered 40/40 product-positive cases with 0/40 unsafe direct-use, 100% rehydrate recall, 100% trace coverage, and 1,305 average context characters.
- Aionis v0.3 context reliability bundle: https://github.com/ostinatocc/MGBench/blob/main/reports/aionis-v0.3-context-reliability/summary.md
- External Claude Code long-flow case: two separate Claude Code sessions used published Aionis hooks with an isolated Runtime; Aionis injected governed execution context into the later session and recorded tool outcomes, validation, handoff state, and post-run guide recovery.

## Common use cases

- Coding agent execution memory across sessions and context compaction.
- Loop engineering memory for plan, act, validate, repair, and feedback cycles.
- Multi-agent handoff between planner, worker, verifier, and reviewer roles.
- Governance for retrieved candidates from Aionis, Mem0, Zep, Supermemory, Chroma, pgvector, logs, and internal stores.

## Install

```bash
npx aionis setup
OPENAI_API_KEY="your-key" npx aionis setup --provider openai --yes
npm i @aionis/sdk
npx @aionis/mcp@latest --scope my-project
```