SDK and API Surface Matrix
This page is the authoritative map of Aionis public surfaces. Use it to decide which API, SDK method, or integration surface to call, and which outputs are safe to pass to an Agent.
Status Labels
| Status | Meaning |
|---|---|
Primary | Recommended product path for new integrations. |
Stable | Supported public surface, but lower-level than the primary path. |
Integration | A package or plugin surface that delivers the same Runtime contract to a host. |
Operator-only | For review, audit, debugging, or lifecycle control. Do not pass directly to an Agent. |
Advanced | Useful for specific deployments or workflows. Not required for the first integration. |
Internal | Runtime support surface. Do not expose as an Agent-facing product API. |
Do not build | Explicit non-goal. Do not create this as a product surface. |
Recommended Entry Points
| Goal | Use | Agent-facing output | Status |
|---|---|---|---|
| Node or TypeScript Agent host | @aionis/sdk guideAgentContext() | result.agent_prompt | Primary |
| Multi-agent or role-aware host | @aionis/sdk execution.guideAgentContextForRole() | result.agent_prompt | Primary |
| HTTP-only host | POST /v1/guide | agent_context.prompt_text | Stable |
| MCP-capable host | @aionis/mcp aionis_context | agent_prompt | Integration |
| File-reading Agent | @aionis/aifs refresh | .aionis/guide.md | Integration |
| Claude Code | aionis-claude-code hooks | injected Aionis context | Integration |
| External memory backend | POST /v1/memory/govern or SDK governMemory() | agent_context.prompt_text | Stable |
If you are writing a new Node or TypeScript integration, start with:
const context = await aionis.guideAgentContext({
query_text: "Continue from the current accepted route.",
context_mode: "compact_agent",
});
await agent.run(context.agent_prompt);Core Runtime API
| Surface | Runtime API | SDK method | Agent-facing | Status | Notes |
|---|---|---|---|---|---|
| Observe memory and execution evidence | POST /v1/observe | observe(), remember(), execution.observeStep() | No | Primary | Records ordinary facts, execution steps, validation output, and handoffs. |
| Compile raw guide | POST /v1/guide | guide(), execution.guideForRole() | Yes, via agent_context.prompt_text | Stable | HTTP-level governed context. Use mode: "full_power" and context_mode: "compact_agent" for compact execution-memory prompts. |
| Compile SDK Agent context | POST /v1/guide plus resolve calls | guideAgentContext() | Yes, via agent_prompt | Primary | Adds SDK execution contract and resolved inspect/rehydrate evidence around the guide. |
| Compile role-aware SDK Agent context | POST /v1/guide plus resolve calls | execution.guideAgentContextForRole() | Yes, via agent_prompt | Primary | Recommended for planner, worker, verifier, reviewer, and team handoff flows. |
| Attribute feedback | POST /v1/feedback | feedback(), execution.feedbackFromOutcome() | No | Primary | Ties outcome back to memory IDs exposed by a guide. |
| Measure effect | POST /v1/measure | measure(), execution.measureRun() | No | Primary | Builds effect reports and trace-derived skill candidate data. |
| Rehydrate evidence | POST /v1/rehydrate | rehydrate() | Usually no | Stable | Expands compact evidence pointers on demand. Feed only the selected evidence text back to the Agent when needed. |
| Resolve memory evidence | POST /v1/memory/resolve | resolveMemory() | Usually no | Stable | SDK guideAgentContext() uses this to resolve inspect/rehydrate evidence. |
| Govern external memory | POST /v1/memory/govern | governMemory(), governMem0SearchResults() | Yes, via agent_context.prompt_text | Stable | Memory Firewall path for Mem0, Zep, vector DB, markdown, logs, or custom candidates. |
| Forget or lifecycle-control memory | POST /v1/forget | forget() | No | Operator-only | Suppress, unsuppress, activate, or rehydrate with a reason. |
| Operator snapshot | GET /v1/operator/snapshot | operatorSnapshot(), snapshot(), execution.snapshotRun() | No | Operator-only | Runtime state and replay summary for review. |
| Flight Recorder | POST /v1/audit/flight-recorder | flightRecorder() | No | Operator-only | Replays what the Agent could see and what was blocked. |
| Decision trace | POST /v1/debug/memory-decision-trace | No primary SDK helper | No | Operator-only | Debug and dashboard surface. |
| Decision report | POST /v1/audit/memory-decision-report | No primary SDK helper | No | Operator-only | Audit report surface. |
| Health | GET /health | health() | No | Stable | Runtime readiness and provider configuration. |
SDK Surface
| SDK method or helper | Calls | Agent-facing | Status | Use when |
|---|---|---|---|---|
createAionisClient() | N/A | No | Primary | Creating a Runtime client. |
observe() | /v1/observe | No | Primary | You already have a product observe payload. |
remember() | /v1/observe | No | Stable | You want to store an ordinary fact, preference, or note. |
execution.observeStep() | /v1/observe | No | Primary | You are recording an execution step, branch, verifier result, or target files. |
execution.handoff() | /v1/observe | No | Primary | You are recording cross-session or cross-agent continuation state. |
guide() | /v1/guide | Yes, nested | Stable | You want raw HTTP guide response shape. |
guideAgentContext() | /v1/guide, /v1/memory/resolve | Yes, top-level agent_prompt | Primary | You want the easiest Agent-ready context for a Node/TypeScript host. |
execution.guideForRole() | /v1/guide | Yes, nested | Stable | You want raw role-aware guide response shape. |
execution.guideAgentContextForRole() | /v1/guide, /v1/memory/resolve | Yes, top-level agent_prompt | Primary | You want Agent-ready context for planner, worker, verifier, reviewer, or team flows. |
compileExecutionAgentContext() | Local compile helper | Yes, top-level agent_prompt | Advanced | You already have a guide object and need to render the SDK execution contract locally. |
agentPromptFromGuide() | Local extraction helper | Yes, string | Advanced | You only need raw agent_context.prompt_text from a guide. |
feedback() | /v1/feedback | No | Primary | You already have feedback payload. |
feedbackFromGuide() | Local helper | No | Primary | You need a feedback payload tied to a guide trace and used memory IDs. |
execution.feedbackFromOutcome() | /v1/feedback | No | Primary | You record an execution outcome and memory attribution together. |
measure() | /v1/measure | No | Primary | You already have measure input. |
execution.measureRun() | /v1/measure | No | Primary | You measure a run after guide and feedback. |
measureInputFromGuideLoop() | Local helper | No | Stable | You need a bounded measure request from a guide loop. |
traceDerivedSkillCandidatesFromMeasure() | Local helper | No | Stable | You want raw trace-derived skill candidates from a measure result. |
traceDerivedSkillReviewItemsFromMeasure() | Local helper | No | Stable | You want compact review items for operator review. |
governMemory() | /v1/memory/govern | Yes, nested | Stable | You pass external memory candidates into Aionis. |
governMem0SearchResults() | /v1/memory/govern | Yes, nested | Stable | You want a Mem0 drop-in governance boundary. |
rehydrate() | /v1/rehydrate | No | Stable | You need raw evidence behind a compact pointer. |
resolveMemory() | /v1/memory/resolve | No | Stable | You need to resolve an Aionis URI yourself. |
forget() | /v1/forget | No | Operator-only | You are changing lifecycle state with an audit reason. |
snapshot() | /v1/operator/snapshot | No | Operator-only | You need a run or operator snapshot. |
flightRecorder() | /v1/audit/flight-recorder | No | Operator-only | You need replay and audit evidence. |
Integration Surface
| Integration | Package or repo | Agent-facing output | Uses same context semantics | Status | Notes |
|---|---|---|---|---|---|
| SDK | @aionis/sdk | guideAgentContext().agent_prompt | Yes | Primary | Main product path for Node and TypeScript hosts. |
| MCP | @aionis/mcp | aionis_context.agent_prompt | Yes | Integration | Tool bridge for MCP-capable coding Agents. |
| AIFS | @aionis/aifs | .aionis/guide.md | Yes | Integration | File surface for Agents that read workspace files. |
| Claude Code | aionis-claude-code | injected hook context | Yes | Integration | Native lifecycle hooks plus MCP setup. |
| HTTP | Raw Runtime API | lower-level agent_context.prompt_text | Yes | Stable | Use when you are outside TypeScript or need service boundaries; SDK AgentContext remains the recommended final prompt path. |
| Substrate | @aionis/substrate | None as final prompt | No | Advanced | Durable evidence sidecar and recall candidate source. Runtime still governs guide output. |
| Manifest | @aionis/manifest | Runtime handoff evidence | No | Advanced | Workflow and executable manifest layer, not a default Agent context renderer. |
| Dashboard | aionis-dashboard | None | No | Operator-only | Read-only trust window over snapshot, trace, measure, and flight recorder. |
Setup Surface
| Install command | What it does | Status |
|---|---|---|
npx aionis setup | Installs local Runtime, writes .env, installs dependencies, builds Runtime. | Primary |
npx aionis setup --profile full-local | Enables existing AIFS setup guidance and the Zvec ANN candidate index. | Primary local profile |
npx aionis setup --with-zvec-ann | Enables Runtime Zvec ANN candidate index and verifies @zvec/zvec. | Advanced |
npx aionis setup --with-aifs | Prints AIFS setup commands for the Agent workspace. | Integration |
npx aionis setup --with-claude-code | Runs Claude Code onboarding and hook installation. | Integration |
npx @aionis/aifs@latest init | Creates the .aionis/ file surface in an Agent workspace. | Integration |
npx @aionis/mcp@latest | Starts the MCP bridge against a running Runtime. | Integration |
| Manual Substrate install | Installs and configures @aionis/substrate as a sidecar. | Advanced |
There is no separate Full Aionis Runtime. The local full profile composes existing pieces: Runtime, embeddings, AIFS setup guidance, and optional Zvec ANN. Claude Code hooks, MCP, and Substrate remain explicit integration choices.
Do Not Expose To Agents
| Surface | Reason |
|---|---|
memory_packet | Internal product packet. Useful for audit and debugging, not prompt material. |
guide_packet | Internal guide packet. The Agent should receive compiled agent_context, not packet internals. |
memory_decision_trace | Debug surface. Can contain decision internals that should stay in host/operator logs. |
memory_decision_audit | Operator audit report. |
memory_use_receipt | Usually host/operator metadata. Pass only selected summaries if your host needs to explain attribution. |
operator_snapshot | Runtime state snapshot for operators and dashboards. |
flight_recorder | Replay report for audit, not next-turn instruction. |
| raw slots and raw payloads | Rehydrate selectively and only when needed for exact evidence. |
Explicit Non-goals
| Do not build | Why |
|---|---|
| A second SDK final-context method | guideAgentContext().agent_prompt already exists and is the primary SDK path. |
| A second final-Agent-context HTTP endpoint | /v1/guide -> agent_context.prompt_text is the HTTP path; SDK adds agent_prompt for TypeScript hosts. |
| Substrate as Runtime replacement | Runtime SQLite remains the Runtime fact source and admission authority. |
| Dashboard as Agent context | Dashboard is read-only operator review. |
| Benchmark runner inside Runtime | Eval workspaces validate Runtime; they do not define product behavior. |
| Manifest as default Agent context | Manifest can create workflow evidence and handoffs; it is not the default context renderer. |
Related Pages
Last updated on