MATM retrieval should return scoped, reviewed, source-backed agent experience only when it is safe and useful. Similarity alone is not enough; retrieval must filter by scope, status, source, sensitivity, authorization, conflict state, and deprecation state.
Retrieval Steps
- Plan the retrieval: task, consumer identity, project/tenant, allowed scopes, allowed kinds, and required evidence.
- Filter hard: authorization, scope, sensitivity, review status, current/deprecated state, and source availability.
- Retrieve candidates: lexical, structured, graph, vector, or trajectory-state search can be combined.
- Rank responsibly: relevance, task state, producer reliability, freshness, evidence, conflict status, and consumer fit.
- Abstain when needed: missing authorization, weak evidence, only hypotheses, stale/deprecated records, unresolved conflicts, or cross-scope leakage risk.
- Cite results: return record ids, source refs, curation report ids, warnings, and deprecation/conflict notices.
Trust-Aware Ranking Signals
| Signal | Positive use | Warning |
|---|---|---|
| Scope match | Project record used inside same project. | Cross-project records require explicit approval. |
| Evidence quality | Reviewed source refs and artifact hashes. | Evidence record is not automatically the claim. |
| Producer reliability | Past useful trajectories can influence rank. | Do not turn reliability into unconditional authority. |
| Freshness | Recent current records rank over stale ones. | Fresh wrong memory is still wrong. |
| Conflict/deprecation state | Warnings and redirect to replacement records. | Do not hide credible conflicts. |
Non-Normative API Example
The starter bundle includes llm-wiki/matm/examples/reference-api.openapi.yaml as an external-runtime example. It is not a live LLMWikis API.
POST /matm/retrieval-requests
request:
consumer_agent: "consumer.demo"
task: "repair checkout retry"
allowed_scopes: ["project", "agent_team"]
required_metadata: ["source_refs", "status", "scope", "authorization_context"]
response:
abstained: false
citations:
- record_id: "mem_demo_team_procedure_001"
warning: "project-specific validation required before use"