MemoryML Specification

Overview

MemoryML (MML) is a declarative language for defining agent memory schemas, storage mappings, and retrieval strategies. Inspired by LookML's semantic layer approach, MML provides a code-first abstraction over diverse storage backends.

Design Principles

1. Declarative over Imperative - Define what memories look like, not how to store them
2. Schema-First - Validate memory shapes before storage
3. Backend-Agnostic - Same schema maps to any supported backend
4. Version-Controlled - Memory schemas live in git
5. Testable - Unit tests for memory schemas
6. Transparent - Human-readable, auditable definitions

How It Works

The Flow

1. DEFINE (Dev Time)     2. COMPILE (Build)      3. RUNTIME (Execution)
   types/*.mml      -->     MML Parser     -->     Schema Validator
   explores/*.mml   -->     Compiled       -->     Backend Router
   backends/*.yaml  -->     Schema         -->     Storage Layer

Key Insight

Traditional memory systems hardcode storage logic:

# Imperative (current engram)
memory.add(text, user_id=user, metadata={"type": "preference"})

MemoryML separates concerns:

# Declarative (MemoryML)
# types/semantic.mml defines WHAT
# backends/production.yaml defines WHERE
# Application just calls: add_memory(text, type="semantic")

Project Structure

memory/
├── memory.yaml           # Root project configuration
├── types/                # Memory type definitions
│   ├── episodic.mml
│   ├── semantic.mml
│   └── procedural.mml
├── explores/             # Combined retrieval views
│   └── project_context.mml
├── backends/             # Backend configurations
│   ├── development.yaml
│   └── production.yaml
├── policies/             # Retention and privacy
│   └── retention.yaml
└── tests/                # Schema tests
    └── schema_tests.yaml

Memory Types

Episodic (Time-stamped events)

memory_type: episodic
version: "1.0"

schema:
  required:
    timestamp:
      type: datetime
      index: temporal
    content:
      type: text
      embedding: true
    session_id:
      type: uuid

computed:
  recency_score:
    expression: "EXP(-(NOW() - timestamp) / 604800)"

storage:
  primary_backend: vector
  retention:
    default: 90d
    summarized_after: 30d

Semantic (Facts and relationships)

memory_type: semantic
version: "1.0"

schema:
  required:
    subject:
      type: text
      embedding: true
      index: hash
    predicate:
      type: text
      enum: [prefers, knows, uses, dislikes, ...]
    object:
      type: text
      embedding: true

relationships:
  - name: related_to
    target_type: semantic
    cardinality: many_to_many

Procedural (Skills and patterns)

memory_type: procedural
version: "1.0"

schema:
  required:
    pattern_name:
      type: text
      index: hash
    trigger_conditions:
      type: json
    action_sequence:
      type: json
    effectiveness_score:
      type: float
      range: [0, 1]

Explores

Explores define combined retrieval views across memory types:

explore: project_context

sources:
  - type: episodic
    filter: "timestamp > NOW() - INTERVAL '7 days'"

  - type: semantic
    filter: "is_current = true"

  - type: procedural
    filter: "effectiveness_score > 0.5"

retrieval:
  method: hybrid
  components:
    - type: vector_search
      weight: 0.6
    - type: graph_traversal
      weight: 0.3
    - type: recency
      weight: 0.1

  token_budget: 4000

Backends

Backend	Type	Use Case
pgvector	vector	Production semantic search
redis	graph	Relationship traversal
sqlite	relational	Development, lightweight
redis	cache	Hot memory caching

CLI Commands

mml validate              # Validate all .mml files
mml compile --backend=prod # Generate migrations
mml test                  # Run schema tests
mml migrate               # Apply migrations
mml export --format=jsonld # Export for portability

MCP Tools

Tool	Description
add_memory	Store memory with type validation
search_memories	Hybrid search via explores
link_memories	Create typed relationships
get_related	Graph traversal
analyze_intelligence	Knowledge graph health report

For the complete specification including all schema definitions, policy configurations, test formats, and JSON-LD export structure, see the full markdown spec.

View Full Specification