ATTUNE

Purpose

ATTUNE retrieves a ranked, scoped view of memory units from the Field. The agent does not provide a search query — it declares who it is and what it needs. The Field computes relevance and returns ranked results.

Context finds the agent. Not the other way around.

Conformance Level

Level 0+ — all conformant implementations MUST implement ATTUNE.

Request

{
  "scope": "<Scope>",
  "context_hint": "<string | null>",
  "format": "full | summary | ids_only",
  "since_epoch": "<number | null>"
}

Response

{
  "status": "ok",
  "record": ["<ScopedMemoryUnit>"],
  "conflicts": ["<Conflict>"],
  "context_budget": {
    "units_returned": "<number>",
    "units_available": "<number>",
    "tokens_used": "<number | null>",
    "tokens_budget": "<number | null>"
  },
  "epoch": "<number>"
}

ScopedMemoryUnit

{
  "memory_unit": "<MemoryUnit>",
  "relevance_score": "<number>",
  "relevance_reason": "<string>",
  "format": "full | summary"
}

Behavioral Requirements

CORE The Field MUST exclude memory units recorded by the requesting agent, unless the scope explicitly requests them.

CORE The Field MUST exclude memory units with status "retracted" or "superseded".

CORE The Field MUST score each candidate memory unit for relevance and sort results by relevance_score in descending order.

CORE The Field MUST truncate results to respect scope.max_units.

CORE Each returned unit MUST include a relevance_score (0.0–1.0) and a human-readable relevance_reason.

Level 1+ If since_epoch is provided, the Field MUST only return memory units committed at or after that epoch.

CORE The Field MUST include unresolved conflicts relevant to the requesting agent in the conflicts array.

Level 2+ The Field SHOULD also respect scope.max_tokens by estimating token counts and including full content or summaries accordingly.

Relevance Scoring

The protocol does not prescribe a specific scoring algorithm. Implementations MUST produce a relevance score between 0.0 and 1.0 for each candidate.

The following factors are RECOMMENDED at all levels:

• Recency: More recent memory units SHOULD score higher.
• Role alignment: Memory units related to the agent's role SHOULD score higher.
• Type importance: Decisions and contradictions SHOULD score higher than observations.
• Source diversity: Results SHOULD include memory units from multiple agents where possible.

At Level 2+, the following additional factors are RECOMMENDED:

• Semantic similarity: Using vector embeddings to measure content relevance.
• Task relevance: Memory units serving the same or dependent tasks SHOULD score higher.
• Relation proximity: Memory units connected via relations to the agent's current context SHOULD score higher.
• Confidence weighting: Higher-confidence units SHOULD score higher.

Example

Request:

{
  "protocol": "akashik",
  "version": "0.1.0",
  "id": "msg-003",
  "operation": "ATTUNE",
  "agent_id": "strategist-01",
  "session_id": null,
  "epoch": 3,
  "payload": {
    "scope": {
      "role": "strategist",
      "max_units": 10
    },
    "context_hint": "About to draft competitive positioning section"
  }
}

Response:

{
  "status": "ok",
  "record": [
    {
      "memory_unit": {
        "id": "mem-002",
        "mode": "committed",
        "type": "finding",
        "content": "European SaaS market for SMB HR tools is growing at 23% CAGR...",
        "intent": { "purpose": "Validate market size assumption for go-to-market strategy" },
        "confidence": { "score": 0.82, "reasoning": "Based on three independent analyst reports." },
        "source": { "agent_id": "researcher-01", "agent_role": "market_researcher", "session_id": null, "timestamp": "2026-03-01T10:30:00Z" },
        "relations": [],
        "status": "active",
        "epoch": 2
      },
      "relevance_score": 0.85,
      "relevance_reason": "Recent finding from market_researcher. Market sizing is relevant to strategy.",
      "format": "full"
    }
  ],
  "conflicts": [],
  "context_budget": {
    "units_returned": 1,
    "units_available": 1,
    "tokens_used": null,
    "tokens_budget": null
  },
  "epoch": 3
}

Error Codes