Guide

POST /v1/guide

Compile governed context for an Agent before it acts.

Guide is where Aionis turns recalled memory and execution state into use_now, inspect_before_use, do_not_use, and rehydrate surfaces.

Request body

Field	Type	Required	Description
`query_text`	string	Yes	What the Agent is about to do.
`tenant_id`	string	No	Tenant boundary.
`scope`	string	No	Project or workspace boundary.
`mode`	`standard` or `full_power`	No	`full_power` merges execution context and structured execution memory.
`context_mode`	`standard`, `full_power`, or `compact_agent`	No	Use `compact_agent` for prompt-ready context.
`task_context_profile`	`general`, `coding_verifier`, `document_integrity`, `long_qa`, `multi_agent_handoff`, or `loop_engineering`	No	Task posture for Agent context rendering. Defaults to `general`.
`agent_role`	string	No	Role such as agent, planner, worker, verifier, reviewer.
`run_id`	string	No	Current execution session.
`consumer_agent_id`	string	No	Agent that will read the guide.
`consumer_team_id`	string	No	Shared team lane.
`limit`	number	No	Candidate limit, max 200.
`context_char_budget`	number	No	Maximum compact context character budget.
`context_compaction_profile`	`balanced` or `aggressive`	No	Context compression profile.
`include_packets`	boolean	No	Include internal memory and guide packets for debugging.

Example


curl -s http://127.0.0.1:3001/v1/guide \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "query_text": "Continue from the current accepted migration state.",
    "mode": "full_power",
    "context_mode": "compact_agent",
    "task_context_profile": "coding_verifier",
    "consumer_agent_id": "worker-1",
    "consumer_team_id": "checkout-team",
    "run_id": "run-001"
  }'

SDK


const guide = await aionis.guide({
  query_text: "Continue from the current accepted migration state.",
  mode: "full_power",
  context_mode: "compact_agent",
  task_context_profile: "coding_verifier",
  consumer_agent_id: "worker-1",
  consumer_team_id: "checkout-team",
  run_id: "run-001",
});

Response

Important fields:

Field	Meaning
`contract_version`	`aionis_guide_result_v1`.
`guide_trace_id`	Stable handle for feedback attribution. Preserve it.
`agent_context.prompt_text`	Prompt-ready governed context.
`agent_context.task_context_profile`	Profile used to render the Agent context.
`agent_context.use_now_memory_ids`	Memory allowed to directly guide action.
`agent_context.inspect_before_use_memory_ids`	Relevant memory that needs verification.
`agent_context.do_not_use_memory_ids`	Memory blocked from direct action.
`agent_context.rehydrate_memory_ids`	Evidence pointers to expand on demand.
`source_map`	Runtime surfaces used to compile the guide.

Feedback requirement

Use guide_trace_id when you call POST /v1/feedback. Only attribute outcome to memory IDs that this guide exposed.

Task context profiles

task_context_profile is selected by your host or adapter. It does not change recall, storage, lifecycle state, or admission authority. It only changes the Agent-facing posture of the compiled context.

Use common mappings like:

Host task	Profile
Coding task with required tests or validators	`coding_verifier`
Source-grounded long-memory question answering	`long_qa`
Planner/worker/reviewer handoff	`multi_agent_handoff`
Plan-execute-validate-repair loop	`loop_engineering`
File movement, extraction, or document identity work	`document_integrity`

See Task Context Profiles.

Common errors

Problem	Fix
Empty or weak context	Check embeddings, `scope`, and whether evidence was observed.
Useful memory appears under inspect	Verify it before direct use, or send feedback after actual use.
Feedback later fails	Preserve the exact `guide_trace_id` returned by this endpoint.