Memory in 5 Minutes

Give any agent persistent memory in three commands — facts it remembers across sessions, episodes it can look back on, and procedures it applies automatically.

Old envelopes still load. Convert them with initrunner doctor --fix PATH. See Envelope Migration.

Before you start: Memory needs an embedding model. The default is OpenAI text-embedding-3-small — set OPENAI_API_KEY to use it, or set embeddings.provider to switch providers (Google, Ollama, and more). No API keys? Jump to fully local setup.

The 3-Command Flow

initrunner new --template memory  # scaffold a memory-ready role file
initrunner run role.yaml -i                         # chat — the agent can now remember things
initrunner run role.yaml -i --resume               # pick up exactly where you left off

What each command does

initrunner new --template memory

Scaffolds a role YAML pre-configured with memory and a system prompt that instructs the agent to use remember(), recall(), and list_memories(). The generated file looks like this:

name: assistant
description: Agent with long-term memory
spec_version: 3
tags:
  - memory
model: openai:gpt-4o-mini
prompt: |
  You are a helpful assistant with long-term memory.
  Use the remember() tool to save important information.
  Use the recall() tool to search your memories before answering.
  Use the list_memories() tool to browse recent memories.
memory:
  max_sessions: 10
  max_resume_messages: 20
  semantic:
    max_memories: 1000
guardrails:
  max_tokens_per_run: 50000
  max_tool_calls: 20
  timeout_seconds: 300
  max_request_limit: 50

The model line is provider:model shorthand. Change it to switch LLM backends. See Providers for all options.

Episodic memory, procedural memory, consolidation, and embeddings are all on by default and are not written into the scaffold. Add those blocks explicitly when you want to tune them:

memory:
  embeddings:
    provider: openai
    model: text-embedding-3-small
    # api_key_env: OPENAI_API_KEY  # optional: override which env var holds the key
  episodic:
    max_episodes: 500
  procedural:
    max_procedures: 100
  consolidation:
    enabled: true
    interval: after_session

Change provider and model under memory.embeddings to switch embedding backends.

initrunner run role.yaml -i

Starts the agent in interactive mode. The agent has three memory tools available automatically:

• Semantic — remember / recall: store and search arbitrary facts by meaning
• Episodic — record_episode: log experiences; auto-captured in autonomous and daemon modes
• Procedural — learn_procedure: save reusable rules that are auto-injected into the system prompt on future sessions

Every session is saved to ~/.initrunner/memory/<agent-name>.lance. Re-running without --resume starts a fresh context window but long-term memories persist.

initrunner run role.yaml -i --resume

Reloads the previous session's messages (up to max_resume_messages: 20 by default) so the conversation continues exactly where it left off. Semantic, episodic, and procedural memories are always available regardless of whether you resume.

Inspect and Manage Memory

initrunner memory list role.yaml                      # show all stored memories
initrunner memory list role.yaml --type semantic      # filter by memory type
initrunner memory consolidate role.yaml               # extract facts from episodes
initrunner memory export role.yaml -o memories.json   # export to JSON
initrunner memory import role.yaml memories.json      # import from JSON
initrunner memory clear role.yaml                     # wipe all memory for this agent

Embedding API Key

The embedding key is read from an environment variable. The default depends on your provider:

Anthropic users: Anthropic has no embeddings API. The default fallback is OpenAI — set OPENAI_API_KEY (in your environment or ~/.initrunner/.env) if keeping that default. To avoid needing an OpenAI key, set embeddings.provider: google or embeddings.provider: ollama instead.

Override the key name — if your key is stored under a different env var name, set api_key_env in the embedding config:

memory:
  embeddings:
    provider: openai
    # api_key_env: OPENAI_API_KEY  # optional override

Diagnose key issues with the doctor command:

initrunner doctor

The Embedding Providers section shows which keys are set and which are missing.

Fully Local — No API Keys

Swap both the LLM and the embedding model to Ollama for a completely local setup:

model:
  provider: ollama
  name: llama3.2
memory:
  embeddings:
    provider: ollama
    model: nomic-embed-text

Then run the same three commands — no API keys required.

Next Steps

• Memory reference — full configuration options, memory types, consolidation, and storage details
• Providers — all supported LLM and embedding backends
• Flow — share a memory store across multiple agents