Memory

The Memory primitive defines how the agent persists and retrieves information across sessions. It supports multiple storage backends, search strategies, retention policies, and optional cognitive semantics such as role, salience, confidence, and forgetting strategy.

URI pattern: claw://local/memory/{name}

---

Schema

claw: "0.3.0"
kind: Memory
metadata:
  name: "hybrid-memory"
  version: "1.0.0"
spec:
  stores:
    - name: "conversations"
      type: "conversation"
      role: "episodic"
      backend: "sqlite"
      retention:
        max_entries: 10000
      compaction:
        enabled: true
        strategy: "summarize"     # "summarize" | "truncate" | "sliding-window"
      lifecycle:
        acquisition: "event-driven"
        consolidation: "adaptive"
        retrieval: "contextual"
      forgetting:
        strategy: "adaptive"
        signals: ["recency", "reuse", "task_outcome", "contradiction"]
      salience:
        enabled: true
        signals: ["novelty", "goal_relevance", "user_preference"]
      confidence:
        source_tracking: true
        decay: "optional"

    - name: "knowledge"
      type: "semantic"
      role: "semantic"
      backend: "sqlite-vec"
      embedding:
        provider_ref: "embedding-provider"
        model: "text-embedding-3-small"
        dimensions: 1536
      search:
        strategy: "hybrid"        # "vector-only" | "fts-only" | "hybrid"
        fusion: "reciprocal-rank"
        top_k: 10

    - name: "facts"
      type: "key-value"
      role: "semantic"
      backend: "sqlite"
      scope: "per-identity"
      encryption: false

    - name: "workspace"
      type: "workspace"
      role: "procedural"
      path: "~/.claw/workspaces/{identity_name}/"
      isolation: "per-channel"
      max_size_mb: 500

    - name: "planner-checkpoints"
      type: "checkpoint"
      role: "working"
      backend: "sqlite"
      checkpoint:
        max_snapshots: 8
        ttl: "24h"

---

Key Fields

Field	Required	Description
stores	Yes	At least one memory store definition.
stores[].name	Yes	Unique store name within the Memory primitive.
stores[].type	Yes	One of conversation, semantic, key-value, workspace, checkpoint.
stores[].role	No	Cognitive role: sensory, working, episodic, semantic, procedural.
stores[].backend	Yes	Storage backend implementation.
stores[].retention	No	Retention policy with max_age and/or max_entries.
stores[].compaction	No	Automatic compaction configuration.
stores[].lifecycle	No	Acquisition, consolidation, and retrieval policy hints.
stores[].forgetting	No	Forgetting and decay policy.
stores[].salience	No	Signals that increase retention or retrieval priority.
stores[].confidence	No	Provenance and confidence decay tracking.
stores[].embedding	Conditional	Embedding configuration. Required for semantic type stores.
stores[].search	No	Search strategy for semantic stores.
stores[].scope	No	Scoping: global, per-identity, or per-channel.
stores[].path	Conditional	Filesystem path. Required for workspace type stores.

---

Store Types

Type	Purpose	Query Pattern
conversation	Chat history and interaction logs	Sequential, time-based
semantic	Knowledge base and long-term facts	Vector similarity + full-text search
key-value	Persistent settings and user preferences	Exact key lookup
workspace	Files, documents, generated artifacts	Filesystem operations
checkpoint	Resumable task state and planner snapshots	Exact lookup by task or execution step

---

Path Template Variables

Path values MAY contain template variables in {variable} syntax. The runtime MUST resolve these before filesystem access.

Standard variables:

• {identity_name} — The agent’s Identity name
• {tenant_id} — Tenant identifier (for multi-tenant deployments)

---

Validation Rules

• The stores array MUST contain at least one entry.
• Each store MUST have a name, type, and backend.
• For semantic stores, the embedding configuration is REQUIRED.
• For workspace stores, the path field is REQUIRED.
• Path template variables MUST be resolved by the runtime before any filesystem access.

---

Cognitive Extensions

CKP 0.3.0 treats Memory as more than storage. The optional cognitive fields help runtimes express:

• what a store represents (role)
• how entries are consolidated and retrieved (lifecycle)
• how stale or low-value entries decay (forgetting)
• which signals matter most (salience)
• whether provenance and confidence are tracked (confidence)

These fields are intentionally policy-like. They describe behavior without forcing a single algorithm.

Design Rationale

The Memory primitive supports five store types (conversation, semantic, key-value, workspace, checkpoint) with hybrid search, automatic compaction, and optional cognitive semantics. The schema is backend-agnostic — from SQLite for embedded devices to PostgreSQL + pgvector for enterprise deployments. This unifies the diverse memory patterns observed across Claw implementations into a single portable declaration.