Skip to Content

Memory

AI-powered cognitive memory system for intelligent agents.

Overview

The memory_service (port 8223) implements a sophisticated multi-layered cognitive memory system inspired by human memory architecture.

Latest Updates (2026-05-17)

  • Memory service now exposes aggregate stats through GET /api/v1/memories/stats?user_id=....

Memory Types

Memory TypeDescriptionStorageRetrieval
WorkingActive context, current focusRedisKey-value
SessionConversation contextRedisSession ID
EpisodicPersonal experiences, eventsQdrantSemantic search
SemanticFacts, concepts, knowledgeQdrantSemantic search
ProceduralHow-to knowledge, skillsPostgreSQLStructured query
FactualSubject-predicate-object factsPostgreSQLStructured query

Working Memory

Store Working Memory

curl -X POST "http://localhost:8223/api/v1/memory/working" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "current_task",
    "value": {"task_id": "task_123", "description": "Writing documentation"},
    "ttl_seconds": 3600
  }'

Get Working Memory

curl "http://localhost:8223/api/v1/memory/working/current_task" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Episodic Memory

Store Episodic Memory

curl -X POST "http://localhost:8223/api/v1/memory/episodic" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User completed their first project deployment successfully",
    "timestamp": "2024-01-28T15:30:00Z",
    "emotion": "proud",
    "importance": 0.8
  }'

Search Episodic Memory

curl -X POST "http://localhost:8223/api/v1/memory/episodic/search" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "project deployment success",
    "time_range": {"from": "2024-01-01", "to": "2024-01-31"},
    "limit": 10
  }'

Semantic Memory

Store Semantic Memory

curl -X POST "http://localhost:8223/api/v1/memory/semantic" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "concept": "Docker",
    "definition": "A platform for running applications in containers",
    "category": "technology",
    "related_concepts": ["containers", "kubernetes"]
  }'

Factual Memory

Store Fact

curl -X POST "http://localhost:8223/api/v1/memory/factual" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "user_123",
    "predicate": "prefers",
    "object": "dark_theme",
    "confidence": 1.0
  }'

Query Facts

curl -X POST "http://localhost:8223/api/v1/memory/factual/query" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject": "user_123", "predicate": "prefers"}'

Procedural Memory

Store Procedure

curl -X POST "http://localhost:8223/api/v1/memory/procedural" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deploy_to_kubernetes",
    "description": "Deploy application to Kubernetes",
    "steps": [
      {"order": 1, "action": "Build Docker image"},
      {"order": 2, "action": "Push to registry"},
      {"order": 3, "action": "Apply manifests"}
    ]
  }'
curl -X POST "http://localhost:8223/api/v1/memory/search" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user preferences for code editor",
    "memory_types": ["episodic", "semantic", "factual"],
    "limit": 10
  }'

Memory Stats

curl "http://localhost:8223/api/v1/memories/stats?user_id=user_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

The stats response summarizes memory-service state for the requested user and is useful for health dashboards, debugging, and agent memory audits.

Memory Consolidation

curl -X POST "http://localhost:8223/api/v1/memory/consolidate" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "extract": ["episodic", "semantic", "factual"],
    "importance_threshold": 0.5
  }'

Python SDK

from isa_user import MemoryClient
 
memory = MemoryClient("http://localhost:8223")
 
# Store episodic memory
await memory.store_episodic(
    token=access_token,
    content="User completed project setup",
    emotion="satisfied",
    importance=0.7
)
 
# Store fact
await memory.store_fact(
    token=access_token,
    subject="user_123",
    predicate="likes",
    object="python"
)
 
# Search memories
results = await memory.search(
    token=access_token,
    query="python programming preferences",
    memory_types=["episodic", "semantic", "factual"]
)

RAG Integration

# Use memory for RAG context
memories = await memory.search(
    token=access_token,
    query=user_question,
    limit=5
)
 
context = "\n".join([m.content for m in memories])
 
# Generate response with memory context
response = await llm.generate(
    prompt=f"Context from memory:\n{context}\n\nQuestion: {user_question}"
)

Next Steps

Home