OASIS Learn/Module 17
Advanced ⏱ 35 min WEB6

Holonic Memory

Holonic Memory is the persistent, fractal memory system that backs every WEB6 AI agent. Memory is organised in a four-level hierarchy — Session, Agent, User, Group — where each level inherits context from levels above it. A Leela assistant in SovereignTrust remembers not just the current conversation, but the user's full trust portfolio history, all previous Leela sessions, and shared wisdom from the broader OASIS community.

What you'll build

  • Understand the four-level holonic memory hierarchy
  • Write and read session-scoped memory (per-conversation context)
  • Write and read agent-scoped memory (persistent agent knowledge)
  • Share memory across users at group level
  • Query memory with semantic search
  • Use memory as automatic system-prompt context injection
📦
API reference

WEB6 API Reference — Holonic Memory section ↗ · npm: @oasisomniverse/web6-api ↗

The Holonic Memory Hierarchy

Memory levels (outer levels always visible to inner)
Group Memory     — shared across all members of a group (community wisdom, org policies)
 └─ User Memory  — persistent per avatar (preferences, history, long-term context)
     └─ Agent Memory — per AI agent (domain knowledge, learned patterns)
         └─ Session Memory — per conversation (current turn context, short-term state)
LevelScopeTypical useTTL
SessionSingle conversationCurrent intent, in-progress task state24h
AgentAll sessions for one agentAgent's learned preferences, tool patternsPermanent
UserAll sessions for one avatarUser profile, history, preferencesPermanent
GroupAll members of a groupOrg policies, shared knowledge base, collective memoryPermanent

Write & Read Memory

memory-write.js
import { ai } from './web6.js';

// Write a fact to user-level memory
await ai.memory.write({
  level:   'User',
  ownerId: avatarId,
  key:     'trustPreferences',
  value:   { jurisdiction: 'England and Wales', preferredTrustType: 'Discretionary' },
  tags:    ['legal', 'preferences'],
});

// Write to session memory (current conversation only)
await ai.memory.write({
  level:     'Session',
  sessionId: currentSessionId,
  key:       'currentDocumentId',
  value:     docId,
});
memory-read.js
// Read a specific key
const { result: prefs } = await ai.memory.read({
  level:   'User',
  ownerId: avatarId,
  key:     'trustPreferences',
});

console.log('Jurisdiction:', prefs.value.jurisdiction);

Memory supports vector search — find relevant context by meaning, not just key lookup.

memory-search.js
// Semantic search: "what does this user know about trusts?"
const { result: hits } = await ai.memory.search({
  query:   'trust deed jurisdiction preferences',
  ownerId: avatarId,
  levels:  ['User', 'Agent'],   // search across these levels
  topK:    5,
});

hits.forEach(h => console.log(h.key, '(' + h.score.toFixed(2) + ')', h.value));

Auto-Injecting Memory into AI Calls

The most powerful pattern: tell WEB6 to automatically prepend relevant memory as system-prompt context on every AI call — no manual lookup needed.

memory-inject.js
const { result } = await ai.chat.complete({
  messages: [{ role: 'user', content: 'Should my trust be discretionary or fixed?' }],
  provider: 'anthropic',
  model:    'claude-3-5-sonnet',
  memoryContext: {
    avatarId,
    sessionId,
    injectLevels: ['Session', 'User', 'Group'],  // inject these automatically
    topK: 8,                                         // top 8 relevant memories
  },
});

// The AI call automatically received the user's jurisdiction preferences,
// previous trust discussions, and community-wide legal knowledge — without
// any extra code on your side.
console.log(result.content);

Group Memory — Shared Knowledge Base

group-memory.js
// Write a policy to the SovereignTrust group memory
await ai.memory.write({
  level:   'Group',
  ownerId: sovereignTrustGroupId,
  key:     'legalPolicy:2026',
  value:   'All trust deeds must comply with Trustee Act 2000 and HMRC IHT400 guidance.',
  tags:    ['legal', 'compliance', '2026'],
});

// Any avatar in the group can now benefit from this knowledge
// when they chat with Leela — it's injected automatically.
💡
You've completed all 17 modules

You now know the full OASIS stack — WEB4 identity and storage, WEB5 game mechanics and spatial worlds, and WEB6 AI agents and memory. The next step is picking a case study that matches what you want to build and following it step by step.

Explore the case studies