Memory Govern

POST /v1/memory/govern is the backend-agnostic admission endpoint behind Memory Firewall. It accepts external memory candidates and returns a governed Agent context plus a decision record.


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

No external candidate is written into Runtime memory by default.

Request


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 the migration from the accepted path.",
    "include_records": true,
    "candidates": [
      {
        "external_memory_id": "external_001",
        "source_backend": "mem0",
        "text": "The legacy adapter path failed verifier review.",
        "authority": {
          "source_trust": "trusted",
          "scope": "project",
          "evidence_requirement": "inspect_before_use"
        },
        "metadata": {
          "target_files": ["src/checkout/legacyAdapter.ts"]
        },
        "lifecycle_hint": "failed",
        "evidence_refs": ["mem0://external_001"]
      },
      {
        "external_memory_id": "external_002",
        "source_backend": "mem0",
        "text": "The accepted path is the new checkout adapter.",
        "authority": {
          "source_trust": "trusted",
          "scope": "project",
          "evidence_requirement": "none"
        },
        "metadata": {
          "target_files": ["src/checkout/adapter.ts"]
        },
        "lifecycle_hint": "current",
        "evidence_refs": ["mem0://external_002"]
      }
    ]
  }'

Candidate Fields

Field	Required	Meaning
`external_memory_id`	Yes	Stable ID from the external backend.
`text`	Yes	Candidate content.
`source_backend`	Yes	Backend name, such as `mem0`, `zep`, or `vector-db`.
`lifecycle_hint`	No	Optional hint such as `current`, `failed`, `stale`, or `procedure`.
`authority`	No	Source trust, scope, and evidence requirement.
`metadata.target_files`	No	Useful for execution-memory route analysis.
`metadata.scope`	No	External scope, if different from request scope.

Hints are not authority. Aionis uses them as evidence and still applies Runtime admission gates.

Response

The response includes:

Field	Meaning
`agent_context.prompt_text`	Context you can give to the Agent.
`memory_admission_record`	Per-candidate action, reason, and prompt inclusion.
`memory_firewall_summary`	Counts and risk summary for the admission pass.
`memory_use_receipt`	Compact prompt-facing audit.

Example decision shape:


{
  "memory_id": "external_001",
  "admission_action": "do_not_use",
  "reason": "Candidate carries failed-branch evidence and must not guide the next action.",
  "prompt_included": true,
  "prompt_surface": "do_not_use"
}

prompt_included can be true for a blocked memory because Aionis may include a short warning in the contract. That does not mean the candidate is allowed for direct action.

Modes

Mode	Use when
`firewall`	You want a strict governance pass before prompt use.
`admission`	You want records and routing without positioning the result as a security firewall.

SDK Helper


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

For Mem0-style result objects:


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

Safety Boundary

This endpoint does not mutate external memory, delete external records, or claim source truth. It only decides how candidate memory may influence the next Agent context.