Module memory_schema 

Canonical Memory Schema for LLM Agents

This module defines the core semantic schema for SochDB as an LLM memory store:

• episodes - Task/conversation runs with summaries and embeddings
• events - Steps within episodes (tool calls, messages, etc.)
• entities - Users, projects, documents, services, etc.

Design Rationale

Without a canonical core, LLMs must reason over O(T) unrelated table schemas. With this fixed (episodes, events, entities) core, effective complexity becomes O(1) + domain-specific tables.

Retrieval Pattern

1. Vector search over episode summaries: O(log E) via HNSW/Vamana
2. Range scan over events by (episode_id, seq): O(V) where V = events per episode

Example Queries

-- Find similar past tasks
SEARCH episodes BY SIMILARITY($query) TOP 5

-- Get timeline for an episode
SELECT * FROM events WHERE episode_id = $id ORDER BY seq

-- Find entities by kind
SEARCH entities WHERE kind = 'user' BY SIMILARITY($query) TOP 10

Structs

Entity

An entity represents a user, project, document, service, etc.

EntityFacts

Facts about an entity

EntitySearchResult

Result of searching entities

Episode

An episode represents a bounded task or conversation run

EpisodeSearchResult

Result of searching episodes

Event

An event represents a single step within an episode

EventMetrics

Performance metrics for an event

TableSemanticMetadata

Semantic metadata for a table (exposed via MCP resources)

Enums

EntityKind

Entity kinds for categorization

EpisodeType

Episode types for categorization

EventRole

Event roles (who/what triggered the event)

TableRole

Table role for semantic metadata

Traits

MemoryStore

Core memory operations trait