Memory

Machines can store information in semantic memory with remember and retrieve it with recall. This is how you build knowledge bases, maintain conversation history, and implement retrieval-augmented generation (RAG). Both operations are governed effects: the runtime checks memory permissions, mediates the operation, and records it in the behavioral ledger.

remember: storing data

remember <name>
  content: <expression>
  collection: "<collection_name>"
  metadata: { <key>: <value> }
  namespace: "<namespace>"
  ttl: "<duration>"

The content is automatically embedded using the collection’s embedding model and stored in the vector database.

remember store_document
  content: input.document
  collection: "knowledge_base"
  metadata: {
    source: input.url,
    category: input.category,
    ingested_at: now()
  }

Configuration

Config	Required	Description
content	Yes	Text or data to store. Automatically embedded.
collection	Yes	Target collection. Created automatically if it does not exist.
metadata	No	Key-value pairs for filtering during recall.
namespace	No	Logical partition (e.g., per-user, per-session).
ttl	No	Time-to-live. Entry removed after this duration ("30d", "24h").

recall: retrieving data

recall <name>
  query: <expression>
  collection: "<collection_name>"
  limit: <number>
  threshold: <number>
  filter: { <key>: <value> }

The query is embedded at runtime and compared against stored vectors. Results are returned ranked by similarity.

recall find_relevant
  query: input.question
  collection: "knowledge_base"
  limit: 5
  threshold: 0.7

Output shape

A recall step returns:

Field	Type	Description
results	list	Matching entries, each with content, metadata, and score
count	number	Number of results returned

Each result has: content (the stored text), metadata (the key-value pairs from remember), and score (similarity, 0.0 to 1.0).

The RAG pattern

The most common use of memory: retrieve relevant context, then feed it to an LLM.

machine question_answerer
  accepts
    question as text, is required
  responds with
    answer as text
    sources as list
  behaves
    recall find_docs
      query: input.question
      collection: "knowledge_base"
      limit: 5
      threshold: 0.7
    compute build_context
      let docs = steps.find_docs.results
      {
        context: docs.map(d => d.content).join("\n\n---\n\n"),
        source_urls: docs.map(d => d.metadata.source)
      }
    ask answer, using: "anthropic:claude-sonnet-4-6"
      with role "Answer based only on the provided context. If the context does not contain the answer, say so."
      with task "Question: ${input.question}\n\nContext:\n${build_context.context}"
      returns
        answer as text
    compute format
      {
        answer: steps.answer.answer,
        sources: build_context.source_urls
      }
  ensures
    permissions
      allowed to
        model
        memory
  verifies
    test "answers from recalled documents"
      assuming find_docs {results: [{content: "Vacation is 20 days.", metadata: {source: "handbook.md"}}]}
      assuming answer {answer: "New employees get 20 days."}
      given {question: "How many vacation days?"}
      expect {answer: "New employees get 20 days.", sources: ["handbook.md"]}

This pattern has three steps: recall relevant documents, build a context string, and pass it to the LLM.

Conversation memory

Store and retrieve conversation history for agents:

machine conversation_agent
  accepts
    message as text, is required
    session_id as text, is required
  responds with
    reply as text
  behaves
    recall get_history
      query: input.message
      collection: "conversations"
      namespace: input.session_id
      limit: 5
    ask respond, using: "anthropic:claude-sonnet-4-6"
      with role "You are a helpful assistant. Use the conversation history for context."
      with task "Previous context:\n${steps.get_history.results.map(r => r.content).join(\"\\n\")}\n\nUser: ${input.message}"
      returns
        reply as text
    remember save_turn
      content: "User: " + input.message + "\nAssistant: " + steps.respond.reply
      collection: "conversations"
      namespace: input.session_id
      ttl: "90d"
  ensures
    permissions
      allowed to
        model
        memory
  verifies
    test "replies with conversation context"
      assuming get_history {results: [{content: "User: Hi"}]}
      assuming respond {reply: "I can help with that."}
      assuming save_turn {ok: true}
      given {message: "Can you help?", session_id: "sess_1"}
      expect {reply: "I can help with that."}

The namespace parameter isolates each session’s history. The ttl ensures old conversations are cleaned up.

Filtered recall

Use filter to narrow results by metadata:

recall find_complaints
  query: "product quality issues"
  collection: "customer_feedback"
  filter: {category: "complaint", urgency: "high"}
  limit: 10
  threshold: 0.6

Only entries whose metadata matches all filter key-value pairs are searched.

Governance

Both remember and recall require memory capability in the ensures section. In test mode, remember is recorded but does not write to the vector store. recall returns empty results by default in test mode (use assuming in verifies tests to mock results).

Try it

Build a knowledge base pipeline: one machine that ingests documents (with remember), and another that answers questions about them (with recall and ask ... using). Store category and source URL as metadata, and filter by category during recall.

Next steps

• Composition - Connecting the ingest and query machines
• Actions - Other action types
• remember reference - Full specification
• recall reference - Full specification