Govern Memory

POST /v1/memory/govern

Govern internal or external memory candidates through Aionis admission.

Use this endpoint when another system has already retrieved candidate memory and you want Aionis to decide what can enter the Agent context.

Request body

Field	Type	Required	Description
`query_text`	string	Yes	What the Agent is about to do.
`candidates`	array	Yes	Candidate memory objects from Aionis or an external backend.
`tenant_id`	string	No	Tenant boundary.
`scope`	string	No	Project or workspace boundary.
`run_id`	string	No	Current execution session.
`mode`	`standard`, `strict`, or `firewall`	No	Use `firewall` for a strict Memory Firewall pass.
`context_mode`	`standard` or `compact_agent`	No	Use `compact_agent` for prompt-ready context.
`include_records`	boolean	No	Include per-candidate admission records.

Candidate fields

Field	Required	Meaning
`external_memory_id`	Recommended	Stable ID from the source backend.
`text`	Yes	Candidate content.
`source_backend`	Recommended	Backend name such as `mem0`, `zep`, `qdrant`, `markdown`, or `custom`.
`lifecycle_hint`	No	Hint such as `current`, `failed`, `stale`, `contested`, or `procedure`.
`authority`	No	Source trust, allowed scope, and evidence requirement.
`metadata.target_files`	No	File paths useful for execution-memory routing.
`evidence_refs`	No	Source-specific references that can be rehydrated later.

Hints are evidence, not authority. Aionis still applies lifecycle, scope, authority, and prompt-surface gates.

Example


curl -s http://127.0.0.1:3001/v1/memory/govern \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "mode": "firewall",
    "context_mode": "compact_agent",
    "query_text": "Continue from the accepted checkout adapter path.",
    "include_records": true,
    "candidates": [
      {
        "external_memory_id": "mem0_001",
        "source_backend": "mem0",
        "text": "The legacy adapter route failed verifier review.",
        "lifecycle_hint": "failed",
        "metadata": {
          "target_files": ["src/checkout/legacyAdapter.ts"]
        },
        "evidence_refs": ["mem0://mem0_001"]
      },
      {
        "external_memory_id": "mem0_002",
        "source_backend": "mem0",
        "text": "The accepted route is the new checkout adapter.",
        "lifecycle_hint": "current",
        "metadata": {
          "target_files": ["src/checkout/adapter.ts"]
        },
        "evidence_refs": ["mem0://mem0_002"]
      }
    ]
  }'

SDK


const governed = await aionis.governMemory({
  query_text: "Continue from the accepted checkout adapter path.",
  mode: "firewall",
  context_mode: "compact_agent",
  include_records: true,
  candidates,
});

For Mem0-style search results:


const governed = await aionis.governMem0SearchResults({
  query_text: "Continue from the accepted checkout adapter path.",
  mem0_results: await mem0.search("checkout adapter"),
  mode: "firewall",
});

Response

Important fields:

Field	Meaning
`contract_version`	`aionis_memory_admission_result_v1`.
`agent_context.prompt_text`	Prompt-ready governed context.
`memory_use_receipt`	Compact receipt of use and suppression decisions.
`memory_admission_records`	Per-candidate action, reasons, and prompt inclusion.
`memory_firewall`	Firewall summary and risk posture.
`source_map`	Candidate source and routing metadata.

Boundary

/v1/memory/govern does not write external candidates into Runtime memory. It governs how candidates may influence the next Agent context.