Vector Memory

Vector memory is Causet’s declarative RAG layer. You declare which ledger events to embed, how to format their text, and how to partition them. The runtime ingests events asynchronously and retrieves the most relevant snippets when a decision references that memory.

This is separate from application memory — accumulated entity fields built deterministically in core rules. Vector memory is for unstructured, similarity-searchable context (support history, past messages, order notes).

Defining a memory

# memories/customer.memories.causet
memories:
  customer_history:
    source_events:
      - CUSTOMER_NOTE_RECORDED
      - ORDER_PLACED
    partition_by: customer_id
    embedding:
      provider: embeddings          # key from providers: (embedding model)
    content: |
      [{{ event.type }}] customer={{ event.customer_id }}
      note={{ event.note }} author={{ event.author }}
      order={{ event.order_id }} total={{ event.total }} items={{ event.item_summary }}

Field	Required	Description
`source_events`	yes	Ledger event types that trigger ingestion
`partition_by`	yes	Payload field used to scope retrieval (e.g. `customer_id`)
`embedding.provider`	yes	Logical embeddings provider from `providers:`
`content`	yes	Template rendered per event — this text is embedded and stored

The content template supports {{ event.type }}, {{ event.<field> }}, and other event envelope fields available at ingestion time.

Linking memory to a decision

Reference the memory name under decisions.*.memories:

decisions:
  triage_ticket:
    provider: reasoning
    prompt: triage_v1
    emits: TICKET_AI_TRIAGED
    memories:
      - customer_history
    input:
      customer_id: { type: string, required: true }
      # ...

At execution time the runtime:

Reads customer_id from the decision input
Vector-searches records in partition customer_id
Injects formatted snippets into {{ memories.customer_history }} in the prompt

# prompts/triage.prompts.causet
prompts:
  triage_v1:
    instructions: |
      Customer ID: {{ customer_id }}
      Subject: {{ subject }}
      Body: {{ body }}
 
      Relevant customer history (most recent first):
      {{ memories.customer_history }}
 
      Respond with JSON: priority, category, summary, confidence.

Memory retrieval uses the partition field from decision input, not entity state. Ensure the partition key (e.g. customer_id) is passed in op: decision input: bindings.

Ingestion pipeline

Domain event committed to ledger
        │
        ▼
Memory ingestion (enabled per fork in Causet Cloud when using vector memory)
        │
        ├─ Match event type against memories.*.source_events
        ├─ Render content template
        ├─ Call embeddings provider
        └─ UPSERT into causet_memory_records (partition + vector)

Ingestion is async and decoupled from the write path. A CREATE_TICKET decision may run before recent notes are embedded; design flows accordingly (seed memory with earlier intents, or accept slightly stale context).

Storage on Causet Cloud

Vector memory records are persisted per application fork when your plan includes AI memory. Ingestion calls your embeddings provider — configure its API key under Secrets & Keys on the same fork as your active release.

For browser tutorials, use executor: mock on the embeddings provider; no persistence is required.

The default retrieval limit is 10 snippets per memory reference on a decision.

Seeding memory before a decision

In the Support Copilot example, memory is populated before triage:

{ "intent_type": "RECORD_CUSTOMER_NOTE", "customer_id": "cust_1", "note": "Prefers email contact", "author": "agent_7" }
{ "intent_type": "SIMULATE_ORDER", "customer_id": "cust_1", "order_id": "ord_99", "total": 149.99, "item_summary": "Pro plan annual" }

These emit CUSTOMER_NOTE_RECORDED and ORDER_PLACED, which feed customer_history. A subsequent CREATE_TICKET for cust_1 retrieves that context during triage.

When to use vector memory vs entity state

Use entity state (application memory)	Use vector memory
Counts, tallies, structured arrays	Free-text notes, messages, descriptions
Must replay identically from ledger	Semantic “find similar” retrieval
Query via entity snapshot or projection	Query via decision-time similarity search
Updated in core rules	Ingested from configured source events

Many apps use both: entity state for structured profile fields, vector memory for unstructured history in LLM prompts.

Privacy and retention

Memory records are derived from ledger events. They inherit the same retention and compliance constraints as your event stream:

Do not ingest PII you cannot retain under your policy
Partition keys (e.g. customer_id) scope retrieval — wrong partition binding leaks no data across tenants within an app
Erasure requires a defined process for both ledger and derived memory stores