Skip to content
mashin

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

ConfigRequiredDescription
contentYesText or data to store. Automatically embedded.
collectionYesTarget collection. Created automatically if it does not exist.
metadataNoKey-value pairs for filtering during recall.
namespaceNoLogical partition (e.g., per-user, per-session).
ttlNoTime-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:

FieldTypeDescription
resultslistMatching entries, each with content, metadata, and score
countnumberNumber 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


  ensures
    permissions
      allowed to
        llm_call, memory


  implements
    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
      assuming
        answer: "Based on the provided context..."


    compute format
      {
        answer: steps.answer.answer,
        sources: build_context.source_urls
      }

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


  ensures
    permissions
      allowed to
        llm_call, memory


  implements
    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
      assuming
        reply: "I can help with that."


    remember save_turn
      content: "User: " + input.message + "\nAssistant: " + steps.respond.reply
      collection: "conversations"
      namespace: input.session_id
      ttl: "90d"

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