Recall Operations

Query and retrieve memories using multimodal cues, association traversal, timelines, graph subgraphs, and raw journal forensic recall.

recall.query

The primary retrieval operation. Accepts a multimodal cue and returns ranked memories with relevance scores. Text recall searches textual and structured content, summaries, and provided/inferred meta-memory fields such as intent, rationale, evidence excerpts, alternatives, decisions, and tags.

Endpoint: POST /v1/recall/query

Request

json

{
  "cue": {
    "text": "What does the user prefer for their development environment?",
    "emotion": {
      "trust": 0.5,
      "intensity": 0.3,
      "valence": 0.5
    }
  },
  "stores": ["semantic", "episodic"],
  "limit": 10,
  "min_fidelity": 0.1,
  "include_decayed": false,
  "reconsolidate": true,
  "activation_depth": 2,
  "recall_mode": "human"
}

Field	Type	Required	Default	Description
`cue`	RecallCue	Yes	--	Multimodal query cue
`stores`	StoreType[]	No	All stores	Filter to specific stores
`limit`	u32	No	10	Maximum results to return
`min_fidelity`	f64	No	None	Exclude records below this fidelity
`include_decayed`	bool	No	false	Include records below prune threshold
`reconsolidate`	bool	No	true	Strengthen retrieved memories
`activation_depth`	u32	No	2	Hops for spreading activation
`recall_mode`	RecallMode	No	human	"human" (with noise) or "perfect" (exact)

Recall Cue

The RecallCue supports multiple modalities simultaneously:

json

{
  "text": "search query",
  "image": [/* raw image bytes */],
  "audio": [/* raw audio bytes */],
  "emotion": { "joy": 0.8 },
  "temporal": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-19T23:59:59Z"
  },
  "embedding": [0.1, 0.2, 0.3, ...]
}

Response

json

{
  "memories": [
    {
      "record": { /* full MemoryRecord */ },
      "relevance_score": 0.9234,
      "activation_path": ["01916e3a-...", "01916e3b-..."],
      "rendered_content": {
        "blocks": [{ "modality": "text", "format": "text/plain", "data": [/* possibly noisy */] }]
      }
    }
  ],
  "activation_trace": {
    "source_id": "01916e3a-...",
    "activations": [
      { "record_id": "...", "activation_level": 0.85, "hop": 1, "edge_type": "semantic" }
    ]
  },
  "total_candidates": 42,
  "query_metadata": {
    "total_records_scanned": 342,
    "stores_searched": ["semantic", "episodic"],
    "fidelity_filtered": 12
  }
}

query_metadata is optional. When present, it helps explain how much data was scanned and how many candidates were filtered by fidelity constraints.

recall.associate

Traverse the association graph starting from a specific record. Returns memories connected by typed edges.

Endpoint: POST /v1/recall/associate/:record_id

Request

json

{
  "association_types": ["semantic", "temporal", "causal"],
  "depth": 3,
  "min_weight": 0.2,
  "limit": 20
}

Field	Type	Required	Default	Description
`association_types`	AssociationType[]	No	All types	Filter by association type
`depth`	u32	No	2	Maximum traversal depth (hard-capped at 8)
`min_weight`	f64	No	0.1	Minimum edge weight to follow
`limit`	u32	No	10	Maximum results (hard-capped at 256)

Response

json

{
  "memories": [
    {
      "record": { /* MemoryRecord */ },
      "relevance_score": 0.75,
      "activation_path": ["source-id", "hop1-id", "this-id"]
    }
  ],
  "total_candidates": 8
}

recall.timeline

Retrieve memories organized into time buckets within a date range.

Endpoint: POST /v1/recall/timeline

Request

json

{
  "range": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-19T23:59:59Z"
  },
  "granularity": "day",
  "min_fidelity": 0.1,
  "emotion_filter": { "joy": 0.5, "intensity": 0.3 }
}

Field	Type	Required	Default	Description
`range`	TemporalRange	Yes	--	Start and end timestamps
`granularity`	TimeGranularity	No	`hour`	One of `minute`, `hour`, `day`, `week`, `month`
`min_fidelity`	f64	No	None	Fidelity floor
`emotion_filter`	EmotionVector	No	None	Filter by emotional similarity

Response

json

{
  "buckets": [
    {
      "start": "2026-03-18T00:00:00Z",
      "end": "2026-03-19T00:00:00Z",
      "memories": [{ /* RecalledMemory */ }],
      "count": 5
    }
  ]
}

recall.graph

Retrieve a subgraph of memory nodes and their association edges, suitable for visualization.

Endpoint: POST /v1/recall/graph

Request

json

{
  "center_id": "01916e3a-5678-7000-8000-000000000001",
  "depth": 2,
  "edge_types": ["semantic", "causal"],
  "include_meta": true,
  "limit_nodes": 50
}

Field	Type	Required	Default	Description
`center_id`	Uuid	No	None	Anchor node for traversal
`depth`	u32	No	2	Maximum traversal hops
`edge_types`	string[]	No	All types	Filter by association type names
`include_meta`	bool	No	false	Include per-node `MetaMemory` and `meta_edges` from the context graph
`limit_nodes`	u32	No	10	Maximum nodes to return

Response

json

{
  "nodes": [
    { "id": "01916e3a-...", "store": "semantic", "summary": "User preferences", "fidelity": 0.92 }
  ],
  "edges": [
    { "source": "01916e3a-...", "target": "01916e3b-...", "edge_type": "semantic", "weight": 0.85 }
  ],
  "meta_edges": [
    {
      "source_id": "01916e3a-...",
      "target_id": "01916e3b-...",
      "relation": "derived_from",
      "rationale": "This summary was derived from the referenced raw journal record.",
      "confidence": 1.0
    }
  ],
  "total_nodes": 12
}

recall.raw_query

Forensic recall over the preserved raw journal. Returns verbatim raw journal entries matching the query, without any decay or noise applied.

Endpoint: POST /v1/recall/raw

Request

json

{
  "session_id": "sess_abc123",
  "query": "user mentioned their favorite editor",
  "temporal": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-19T23:59:59Z"
  },
  "limit": 10,
  "include_private_scratch": false,
  "include_sealed": false,
  "secrecy_levels": ["public", "sensitive"]
}

Field	Type	Required	Default	Description
`session_id`	string	No	None	Filter to a specific session
`query`	string	No	None	Full-text search query over raw journal content
`temporal`	TemporalRange	No	None	Filter by time range
`limit`	u32	No	10	Maximum results to return
`include_private_scratch`	bool	No	`false`	Include `private_scratch` visibility entries
`include_sealed`	bool	No	`false`	Include `sealed` (encrypted) entries
`secrecy_levels`	SecrecyLevel[]	No	All levels	Restrict to specific secrecy levels

Response

json

{
  "records": [
    {
      "id": "01916e3a-5678-7000-8000-000000000003",
      "session_id": "sess_abc123",
      "turn_id": "turn_001",
      "topic_id": null,
      "source": "conversation",
      "speaker": "user",
      "visibility": "normal",
      "secrecy_level": "public",
      "created_at": "2026-03-15T14:30:00Z",
      "updated_at": "2026-03-15T14:30:00Z",
      "content": { /* MemoryContent */ },
      "metadata": {},
      "derived_memory_ids": ["01916e3a-aaaa-..."],
      "suppressed": false
    }
  ],
  "total_candidates": 42
}

Next Steps

Lifecycle Operations

Manage decay, consolidation, and data portability