Memory System

XYBEROS provides a 6-tier memory system with automatic fallback and promotion.

Tiers

Query → Working (fastest, capacity 1,000)
         ↓ miss
     → Episodic (10,000) + Semantic (10,000) — parallel
         ↓ miss
     → Procedural (configurable)
         ↓ miss
     → Vector Store (embedding-based similarity)
         ↓ miss
     → Knowledge Graph (slowest)
         ↓ hit
     → Promote to Working (fast future access)

Tier	Purpose
Working	Fast, short-term context (LRU, max 1,000)
Episodic	Cycle-level experience storage
Semantic	Extracted facts and knowledge
Procedural	Executable procedures
Vector	Embedding-based similarity search
Knowledge Graph	Node-relationship storage

Using Memory

from xyberos.memory import MemoryManager

manager = MemoryManager()
manager.register_defaults()

# Store a memory
from xyberos.memory import MemoryItem
item = MemoryItem(
    key="my-key",
    content={"message": "Hello world"},
    metadata={"source": "chat"},
)
manager.store(item, tier="working")

# Query
from xyberos.memory import MemoryQuery
result = manager.query(MemoryQuery(
    text="Hello",
    limit=5,
))
for item in result.items:
    print(item.content)

Via xyberos

from xyberos import xyberos

# Store
xyberos.store_memory(
    "user-preference",
    {"theme": "dark"},
    tier="semantic",
)

# Retrieve
memories = xyberos.remember("user preferences", limit=5)

Via REST API

# Store
curl -X POST http://localhost:8080/memory \
  -H "Content-Type: application/json" \
  -d '{"key": "greeting", "content": "Hello!", "tier": "working"}'

# Retrieve
curl "http://localhost:8080/memory?query=hello&limit=5"

# Delete
curl -X DELETE http://localhost:8080/memory \
  -H "Content-Type: application/json" \
  -d '{"key": "greeting", "tier": "working"}'