memory

Source: packages/oracle-runtime-workers/src/plugins/memory/

Summary

Durable memory across conversations — who the user is, what you have made for them, and what worked. Surfaces the upstream Memory Engine MCP tools verbatim (memory-engine__search_memory_engine, memory-engine__add_memory, …). Tool list is resolved per-request because MCP headers depend on the in-flight user's UCAN delegation.

Environment variables

Domain entity and runtime compatibility

The Memory Engine keys memory by the oracle's domain entity (ORACLE_ENTITY_DID), not by the oracle's agent account (ORACLE_DID). A user's personal memory belongs to the pair (user, entity); the shared knowledge spaces (public and private) belong to the entity. Several oracles serving one entity therefore share its knowledge, and rotating an oracle's agent key keeps its users' memory.

Every request names the entity in the x-oracle-entity-did header, and the entity must vouch for the oracle: its on-chain document lists the oracle's agent account (ORACLE_DID) as a linkedEntity with service: matrix and relationship: admin. qiforge-cli create-entity writes that link on the entity it creates; an entity created another way needs one of its controllers to add it.

A user can also reach their own memory with an entity directly, without any oracle, by signing the UCAN invocation alone; the entity must then exist on chain, and the user can do exactly what an oracle acting for them could.

What it contributes

• Tools (default selection):
  • memory-engine__search_memory_engine — recall stored facts.
  • memory-engine__add_memory — write a new memory.
  • memory-engine__add_oracle_knowledge — write knowledge shared with every user of the oracle (@ixo/oracle-runtime-workers 0.21.0 and later; the Memory Engine refuses the call unless the user is a domain member of the oracle entity, see Adding global oracle knowledge).
  • memory-engine__delete_episode — delete a memory.
  • memory-engine__clear — clear (destructive; main-agent only).
• Native tools (@ixo/oracle-runtime-workers 0.26.0 and later, listed only next to the tools above; see Oracle documents):
  • add_oracle_document — store a chat attachment or a Library file as domain knowledge, grouped as one document or as loose facts.
  • list_oracle_documents — list the grouped documents of a knowledge space with their status.
  • delete_oracle_document — delete a grouped document and everything it stored.
• Sub-agents: none.
• Middleware: none directly contributed by the plugin (enrichment of state.userContext is handled upstream of the agent).
• HTTP routes: none.
• Shared state: userProfile — other plugins read it via rtCtx.shared.userProfile.

Tools available beyond the default selection (e.g. memory-engine__delete_edge) can be enabled by passing selectedTools to new MemoryPlugin({ selectedTools: [...] }); the same option, passed without memory-engine__add_oracle_knowledge, hides the oracle-knowledge write from the agent.

On the Cloudflare Workers runtime, the manifest requires memory/* on ixo:memory. A user whose delegation doesn't grant it can't load the plugin or run its tools, and the agent is told what's missing.

From @ixo/oracle-runtime-workers 0.39.0 the plugin stays always, but only the tools of ordinary conversation are bound on every turn: memory-engine__search_memory_engine, memory-engine__add_memory and list_oracle_documents. The curating and deleting tools (memory-engine__add_oracle_knowledge, memory-engine__delete_episode, memory-engine__delete_edge, memory-engine__clear, add_oracle_document, delete_oracle_document) are in onDemandTools: the model loads them with load_capability(['memory']), from the catalogue line "add or delete oracle documents, knowledge; delete memories". The manifest also sets routable: false, so the capability router never preloads them. To bind them all again:

manifestOverrides: { memory: { onDemandTools: [] } },

Search results and deleting a memory

From Memory Engine 2.1.0, memory-engine__search_memory_engine says which stored episodes are behind what it found:

• facts[].episodes lists the UUIDs of the episodes behind each fact, newest first, at most 20. Episodes written together in one burst are attributed together, so a fact can name several episodes and not every one of them is about it. The list is empty when the fact's source is not recorded.
• episodes[] lists matching episodes with uuid, name, content (cut at 600 characters), created_at and knowledge_scope. The tool's max_episodes input sets how many (0 to 20, default 3).

The surest handle for memory-engine__delete_episode is episodes[].uuid, because it comes with the episode's text. A delete answers as soon as the episode itself is gone. Repairing the memories that shared an entity with it, and re-ingesting the other messages of its burst, run in the background once the deletes have been quiet for 5 seconds (at most 60 seconds after the first of a run). Until then, facts from those neighbouring episodes can be missing from search for seconds to minutes.

Oracle documents

From @ixo/oracle-runtime-workers 0.26.0, with Memory Engine 2.3.0 or later (the /knowledge/documents routes; live on devnet, testnet and mainnet), a domain member can hand the oracle a file and ask it to remember it as domain knowledge. The file is a chat attachment (a PDF, a text or Markdown file, a scan or an image) or a file from the user's Library. The oracle reads it (a PDF with a text layer is read page by page in the oracle; a scanned file or an image goes to a helper model, up to 10 MB), cuts it into parts and sends them to the engine in one call.

add_oracle_document takes group_as_document, with no default:

• true keeps the file as one document under a document_id: a board resolution, a contract, a report. list_oracle_documents shows it with its status (ingesting, ready, partial, deleting, delete_failed). Adding the same document_id again replaces it, and delete_oracle_document removes everything it stored. A replace or a delete is answered at once and finishes in the background.
• false stores each part as loose knowledge, for a file where someone collected many unrelated facts. The parts are found by search like any other knowledge and removed one at a time with memory-engine__delete_episode.

The agent is told to ask the person when it cannot tell which one a file is, and to confirm the public or private space before writing. The engine applies the same domain-member rule as for memory-engine__add_oracle_knowledge. A file attached in the chat always goes to add_oracle_document, never to memory-engine__add_oracle_knowledge. Limits: about 750 KB of text per document with the defaults, text files and text PDFs up to 25 MB, scanned files and images up to 10 MB. A PDF that mixes text pages and scanned pages keeps only its text pages. Pass new MemoryPlugin({ documentTools: false }) to leave the three tools out.

How memory reaches the prompt

Memory context does not arrive in the prompt because the agent calls a tool to fetch it. Instead, a UserContextFetcher runs before the main agent is compiled — eagerly loading all six context slots in a single pass, before any message is processed.

What the fetcher loads: six slots, in this order:

1. identity — who the user is (name, role, background)
2. work — ongoing projects and responsibilities
3. goals — stated objectives and priorities
4. interests — topics and domains the user cares about
5. relationships — people and organizations mentioned in past conversations
6. recent — notable things from the last few sessions

When it runs: at agent-compile time, before turn 1. The fetcher runs once per session and caches the result for 5 minutes (keyed by sessionId). Subsequent turns within the same session reuse the cached context — the Memory Engine is not called again unless the cache expires.

What appears in the prompt: if at least one slot is non-empty, the runtime inserts a ## What you know about the user block into the system prompt containing all populated slots. If every slot is empty (no prior memory for this user), the block is omitted entirely.

Implication for oracle authors: you do not need to instruct the agent to "look up the user's context" or "recall memory before responding" in config.prompt.opening or anywhere else. The context is already in the system prompt when the agent sees the user's first message. Adding such instructions is redundant and wastes tokens.

Adding global oracle knowledge

Global knowledge is content the oracle should know on every turn, for every user — product docs, brand voice, FAQs, reference material. It's stored on the Memory Engine and indexed under the oracle's entity DID, not the user's DID.

// src/index.ts
import {
  createOracleWorker,
  BUNDLED_WORKERS_PLUGINS,
  MemoryPlugin,
  DEFAULT_MEMORY_TOOLS,
  MEMORY_ADD_ORACLE_KNOWLEDGE_MCP_NAME,
} from '@ixo/oracle-runtime-workers';

export default createOracleWorker({
  config,
  plugins: [
    ...BUNDLED_WORKERS_PLUGINS.filter((plugin) => plugin.name !== 'memory'),
    new MemoryPlugin({
      selectedTools: [
        ...DEFAULT_MEMORY_TOOLS,
        MEMORY_ADD_ORACLE_KNOWLEDGE_MCP_NAME,
      ],
    }),
  ],
});

pnpm dev

https://dev.portal.qi.space/domain/<ENTITY_DID>/connect

Opt out / Opt in

const app = await createOracleApp({
  config,
  features: { memory: false },   // never load
  // features: { memory: true },  // force load (will fail env validation if vars missing)
  // features: { memory: 'auto' }, // run autoDetect (default)
});

When to use it

• First contact (no prior context loaded): greet, ask the user's name and what they need help with, save the answer.
• You learn something durable about the user — name, role, ongoing project, a constraint, a relationship.
• You produce an artifact (file, document, edit, generated content) — record what it is, what it is for, the structural choices.
• The user expresses satisfaction or dissatisfaction with something you produced — capture what worked or did not.
• The user references something they told you before, or something you made before.
• A controller or owner of the oracle types something every user of the oracle should know (a policy, a procedure, reference material): tell them it will be shared with every user of the oracle (or, for the private space, with the domain's members only), get their confirmation, then store it as oracle knowledge rather than as a memory about them.
• A controller or owner hands you a file (an attachment or a Library file) to store as oracle knowledge: use add_oracle_document, grouped for one coherent record, loose for a file of unrelated facts; ask when it is not obvious, and confirm the space first.

When NOT to use it

• Ephemeral conversation-only state — use the current message thread.
• Behavioural preferences about how to respond — use user-preferences.
• Public web facts not specific to this user — use firecrawl.
• Anything the user asked you to forget or framed as temporary.
• Oracle knowledge for something about one user: the shared knowledge is only for what every user of this oracle should know.
• Storing a file the person did not ask you to store, or choosing between a grouped document and loose facts without asking when the file could be either.

Where to read next