Memory Vector Recall

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Semantic memory recall stores per-workload memory entries, embeds eligible content through the configured LiteLLM-compatible embedding endpoint, and ranks matches inside the control plane. Outside local development, semantic recall requires the PostgreSQL pgvector column and index path. Production-like deployments fail closed when vector infrastructure is unavailable.

Recall continues to use the same workload, actor, optional session, expiry, and vector-ranking behavior. Memory entries now also expose typed governance metadata for future recall builders: memory category, source, confirmation, confidence, sensitivity, retention, consent, and redaction posture. See Memory Governance for the complete response shape and write-policy denial contract.

Local development keeps a bounded Python fallback for SQLite and local PostgreSQL rows whose JSON embedding exists before the vector column is populated. The fallback is not a production scaling mode.

Prerequisites

Non-local deployments require the pgvector PostgreSQL extension. Migration 047 adds the embedding_vector column and HNSW index; managed Postgres environments must install the extension before running migrations.

The canonical repository reference is docs/operations/postgres-extensions.md. It covers local Docker Compose, managed Postgres, self-hosted Postgres, and the migration failure mode.

Memory Asset Configuration

Memory behavior is controlled by the active release-bound memory asset. The asset content is normalized into these fields:

Example:

{
  "backend": "postgresql",
  "scope": "session",
  "pii_handling": "redact",
  "retention": {
    "ttl_seconds": 2592000,
    "max_entries": 500,
    "decay_strategy": "hard_delete"
  },
  "semantic_recall": {
    "enabled": true,
    "embedding_model": "text-embedding-3-small"
  }
}

Bind the memory asset into a release with the role memory. The runtime only uses memory for a workload when the active release has that binding.

API Surface

Read active memory config

curl "http://localhost:8000/v1/memory/workloads/{workload_id}/config?environment=prod"

This returns the active release, bound memory asset, retention settings, PII posture, and semantic recall settings.

List entries

curl "http://localhost:8000/v1/memory/workloads/{workload_id}/entries?actor_ref=user:alice&session_id=session-1"

The authenticated actor must match actor_ref unless the caller is an internal service carrying the matching x-orqestra-execution-actor-ref header.

Append an entry

curl -X POST "http://localhost:8000/v1/memory/workloads/{workload_id}/entries" \
  -H "Content-Type: application/json" \
  -d '{
    "actorRef": "user:alice",
    "sessionId": "session-1",
    "memoryAssetVersionId": "mem-version-123",
    "role": "assistant",
    "content": "Alice prefers short executive summaries.",
    "memoryType": "preference",
    "metadata": {"source": "assistant"}
  }'

When semantic recall is enabled, append computes an embedding before writing the entry only after the governed memory write policy allows the content. If the embedding provider returns an incompatible vector dimension, the API returns 502. If the vector index is required but unavailable, it returns 503.

Recall entries

curl -X POST "http://localhost:8000/v1/memory/actors/user:alice/recall" \
  -H "Content-Type: application/json" \
  -d '{
    "workloadId": "{workload_id}",
    "environment": "prod",
    "query": "executive summary",
    "sessionId": "session-1",
    "topK": 5,
    "policyOverride": {
      "memoryTypeAllowed": ["preference", "fact"],
      "diagnosticsVerbosity": "summary"
    }
  }'

topK is bounded to 1-20. If the memory asset scope is session, sessionId is required. The route resolves scope from the active release-bound memory asset; callers do not select a broader scope in the request. Recall first requires an exact match on each stored MemorySession.scope: workload scope may include both authorized subjects in the workload, actor scope is private to the requesting actor, and session scope is private to the requesting actor and the exact session reference. If semantic recall is disabled, the endpoint returns 400. Recall returns an envelope with entries and diagnostics; diagnostics include bounded candidate decisions and the scope-query, policy-filter, and vector-rank counts. Per-request policyOverride can change only axes the workspace policy marks as relaxable. Overrides on non-relaxable axes return USER_OVERRIDE_NOT_PERMITTED.

Purge entries

curl -X DELETE "http://localhost:8000/v1/memory/workloads/{workload_id}/entries?actor_ref=user:alice&session_id=session-1"

Purge emits a memory.purged governance audit event with the actor scope, session scope, and purged count.

Manage existing entries

Memory management routes operate on entry ids and are governed by the same workspace and actor checks as inspect and purge. Same-actor controls require memory.write or memory.admin; cross-actor controls require memory.admin.

The lifecycle filter accepts active, stale, superseded, suppressed, and disabled.

Export entries

curl "http://localhost:8000/v1/memory/exports?actorRef=user:alice&workspaceId={workspace_id}&includeLifecycleStates=active,disabled&pageSize=100"

Export returns a paginated JSON envelope with entries and nextPageToken. The only supported format is jsonl. Page tokens are HMAC-protected and non-local deployments must set ORQESTRA_MEMORY_EXPORT_PAGE_TOKEN_SECRET.

Runtime Behavior

At execution time, the runtime fetches the active memory config and matching entries alongside the release context. When a workload appends new memory after execution, hierarchy fields from the execution context are forwarded to the control plane so memory rows stay workspace-scoped.

Memory entries with attacker-shaped content are quarantined before they are prepended into model prompts. The runtime replaces unsafe memory text with a bounded placeholder and records a memory_context_quarantined warning.

Configuration

Hot Path Behavior

• Recall filters by workload, exact stored session scope, actor/session where required, expiry, and workspace before policy filtering and ranking.
• Unknown scopes and session-scoped recall without a session reference return no repository hits; the public release-bound route separately rejects a missing required sessionId with a client error.
• Context recall policy filters typed memory fields before vector ranking and returns bounded diagnostics without raw content or metadata.
• Expired rows are filtered from recall; cleanup runs outside the recall hot path.
• Embedding calls use ORQESTRA_MEMORY_EMBEDDING_TIMEOUT_SECONDS and an in-process circuit breaker to avoid repeated long waits on provider failure.
• Non-local deployments require the vector index by default.
• Local deployments can fall back to Python cosine similarity when the vector index is not required.

Spatial Memory Routes

Spatial memory adds platform-admin-gated APIs for spaces, rooms, and links:

These routes are platform-admin gated while scope-specific authorization is hardened. Treat them as administrative topology tools, not end-user memory controls.

Failure Modes

See Memory Governance for lifecycle and write-policy rules, and operator context provenance for the separate turn-provenance API contract.

Assistant summary and acknowledgement

The assistant summary is a workspace-scoped, actor-specific aggregation of existing governed state. Use these authenticated API paths relative to your deployment’s control-plane address:

GET /v1/assistant/summary?workspace_id={workspace_id}
POST /v1/assistant/summary/ack?workspace_id={workspace_id}

Both require assistant.summary.view in the target workspace. The actor comes from authentication; callers cannot select another user’s summary. Cross-workspace aggregation is not enabled.

The GET does not advance last_seen_at or last_home_summary_at. To acknowledge the snapshot actually displayed, POST a body containing its generated_at value as observed_generated_at:

{
  "observed_generated_at": "2026-10-18T09:00:00Z"
}

The server records its current time as last_seen_at, clamps future snapshot timestamps to server time, and advances the summary cut-off monotonically. Events committed after the displayed snapshot remain eligible for the next since-last-session summary. Do not replace the displayed timestamp with a freshly fetched snapshot when acknowledging a view.

Memory management from SDK and CLI

The Home memory panel uses generic memory operations. These operations are available to integrations through client.memory.list(...), recall(...), purge(...), pin(...), unpin(...), disable(...), enable(...), mark_incorrect(...), edit(...), merge(...), rescope(...), change_retention(...), and export(...). There is no assistant-home-specific SDK or CLI wrapper for the summary surface.

The CLI exposes entry actions and paginated export:

orqestractl memory entry pin {entry_id}
orqestractl memory entry unpin {entry_id}
orqestractl memory entry disable {entry_id}
orqestractl memory entry enable {entry_id}
orqestractl memory entry mark-incorrect {entry_id}
orqestractl memory export --actor-ref {actor_ref} --workspace-id {workspace_id}

Use orqestractl memory entry --help for edit, retention, rescope, and merge inputs. Export returns a paginated JSON envelope; use its page token to continue rather than assuming one response is complete.

Inspection requires memory.read; per-entry management requires memory.write or memory.admin; purge requires memory.purge; cross-actor management or export requires memory.admin. Operations retain actor/workspace authorization, lifecycle and redaction rules. A normal caller cannot inspect or purge another actor’s memory. Purge and management actions produce governance audit events. Exporting or purging memory does not imply exporting or deleting every conversation and audit record.