Full Setup

Use this page when you want to wire Aionis into a real Agent workflow, not just start the Runtime.

The complete setup has four layers:

Runtime + embeddings
  -> recall and evidence surfaces
  -> Agent integration
  -> feedback, replay, and lifecycle controls

1. Install The Runtime

npx aionis setup

For a non-interactive install with embeddings configured:

OPENAI_API_KEY="your-key" npx aionis setup --provider openai --yes

Or:

MINIMAX_API_KEY="your-key" npx aionis setup --provider minimax --yes

Start the Runtime from the installed directory:

cd .aionis-runtime
npm run -s lite:start

Check health:

curl http://127.0.0.1:3001/health

2. Configure Embeddings

Stored-memory recall needs embeddings.

export EMBEDDING_PROVIDER="openai"
export OPENAI_API_KEY="your-openai-key"

MiniMax:

export EMBEDDING_PROVIDER="minimax"
export MINIMAX_API_KEY="your-minimax-key"

Use a consistent embedding configuration for writes and guide-time recall.

3. Enable Substrate

Substrate is the durable evidence sidecar. Add it when you want stronger ordinary-memory recall, backup, migration, preview context, or long-lived audit search.

npm install --save-dev @aionis/substrate

Enable it for Runtime recall:

export RECALL_ENGINE_MODE="hybrid"
export RECALL_SUBSTRATE_SIDECAR_ENABLED="true"
export RECALL_SUBSTRATE_PATH="./data/substrate.sqlite"
export RECALL_SUBSTRATE_FAIL_OPEN="false"

The Runtime remains the admission authority. Substrate can improve candidate coverage, but guide still decides use_now, inspect_before_use, do_not_use, and rehydrate.

4. Enable AIFS

AIFS mirrors governed Runtime output into .aionis/ files for agents that read workspace files well.

npx @aionis/aifs@latest init \
  --base-url http://127.0.0.1:3001 \
  --scope my-project
 
npx @aionis/aifs@latest doctor \
  --base-url http://127.0.0.1:3001 \
  --scope my-project
 
npx @aionis/aifs@latest refresh \
  --base-url http://127.0.0.1:3001 \
  --scope my-project

Point the Agent at:

.aionis/AGENT_INSTRUCTIONS.md

That file tells the Agent how to read current context, blocked memory, rehydrate pointers, receipts, and snapshots.

5. Choose An Integration

Pick one integration surface for your Agent host.

All integration paths map to the same product loop:

observe -> guide -> agent action -> feedback -> measure -> snapshot

6. Set Identity And Scope

Stable identity is what makes Aionis continuous across sessions, agents, and devices.

Most “Aionis did not remember” issues are scope or identity mismatches.

For coding work, a good scope is a stable workspace or repository identity:

scope = "repo:checkout-service"
task_signature = "checkout-migration"
team_id = "checkout-team"

7. Wire The First Agent Loop

Before the Agent acts, call guide:

const guide = await aionis.guide({
  query_text: "Continue the checkout migration from the current accepted path.",
  context_mode: "compact_agent",
  run_id,
  task_signature: "checkout-migration",
  consumer_agent_id: "worker-1",
  consumer_team_id: "checkout-team",
});

After the Agent acts, record what happened:

await aionis.observe({
  run_id,
  task_signature: "checkout-migration",
  agent_id: "worker-1",
  team_id: "checkout-team",
  title: "Worker updated checkout adapter",
  summary: "Implemented the scoped adapter route and avoided the legacy route.",
  outcome: "succeeded",
  target_files: ["src/checkout/adapter.ts"],
});

When you know the outcome, send feedback tied to the guide trace:

await aionis.feedback({
  guide_trace_id: guide.guide_trace_id,
  run_id,
  outcome: "positive",
  used_memory_ids: guide.agent_context?.use_now_memory_ids ?? [],
  reason: "The accepted route was followed and validation passed.",
});

Then measure and snapshot:

await aionis.measure({ run_id });
await aionis.snapshot({ run_id });

8. Configure Multi-Agent Handoff

Use explicit roles and shared team identity.

Use:

memory_lane = "private" for role-private notes
memory_lane = "shared" for handoff and accepted workflow state

Keep team_id stable across roles so Aionis can compile shared execution context without mixing unrelated projects.

9. Preserve Feedback Attribution

Feedback is the loop that lets Aionis learn which memory helped.

Always preserve:

guide_trace_id
used_memory_ids
outcome
used_surface
reason

Do not attribute feedback to memory that was not exposed by that guide. Aionis uses this boundary to keep receipts, Flight Recorder, and future admission data clean.

10. Use Rehydrate And Forget

Aionis keeps context compact. When the Agent needs raw evidence, use rehydrate:

guide -> rehydrate pointer -> raw evidence

When memory should stop influencing future work, use controlled lifecycle operations:

See Rehydrate Evidence and Forget & Suppress.

11. Govern External Memory

If you already use Mem0, Zep, Supermemory, a vector DB, markdown, logs, or an internal memory store, keep it as candidate retrieval and put Aionis in front of Agent prompt use.

external memory candidates
  -> /v1/memory/govern
  -> use_now / inspect_before_use / do_not_use / rehydrate
  -> Agent context

See Govern External Memory.

12. Self-host Checklist

For a self-managed deployment, decide these before exposing Runtime outside a single local machine:

Recommended Full Stack

For most serious local or self-managed Agent workflows:

Runtime + embeddings
  + Substrate
  + one integration surface
  + stable scope/identity
  + feedback attribution
  + Flight Recorder snapshots

Add AIFS when the Agent reads project files. Add MCP or a native plugin when your Agent host supports tool bridges. Add Memory Firewall when another memory system already produces candidates.