Core Concepts

Memento Protocol has five primitives. Each serves a different kind of remembering.

Memories

Long-term storage. A memory has content (free text), a type (fact, decision, observation, instruction), tags for categorization, and an optional expiration date.

Each memory carries a relevance score that decays exponentially over time (7-day half-life). Memories that are accessed frequently resist decay — the system tracks access_count and last_accessed_at to boost frequently recalled memories.

memento_store(
  content: "The Navier-Stokes millennium problem asks whether smooth
            solutions can develop singularities in finite time.",
  type: "fact",
  tags: ["math", "fluid-dynamics", "millennium-problems"],
  expires: "2026-06-01"  // optional TTL
)

Memories can also link to each other, to working memory items, or to files — see Linkages below.

Working Memory

Working memory has two interfaces. Structured items (memento_item_list, memento_item_create, memento_item_update) are the recommended interface — they support categories, priorities, statuses, and next actions. The legacy markdown interface (memento_read, memento_update) stores freeform text in named sections, still useful for injecting raw markdown into system prompts.

The scratchpad. Five default sections:

Section	Purpose
`active_work`	Current tasks and projects in progress
`standing_decisions`	Persistent choices and preferences
`skip_list`	Things to avoid (legacy, see Items)
`activity_log`	Recent actions and events
`session_notes`	Ephemeral notes for the current session

Working Memory Items

Structured entries within working memory. More granular than sections — each item has a category, status, priority (0-10), tags, and optional next_action.

Category	Use for
`active_work`	Things currently being worked on
`standing_decision`	Persistent preferences and rules
`skip_list`	Things to avoid doing
`waiting_for`	Blocked on external input
`session_note`	Temporary notes

Statuses

active → paused → completed → archived

Only active and paused items appear in the context endpoint. Completed and archived items are retained for history.

Skip List

Things the agent should not do, mention, or suggest. Each entry has an item (what to skip), a reason (why), and an optional expiration.

memento_skip_add(
  item: "aurora alerts",
  reason: "Kp too low to see from this latitude. Revisit when Kp > 4.",
  expires: "2026-03-01"
)

Skip entries are checked automatically by the context endpoint on every message. Matches appear as warnings so the agent knows to avoid the topic.

Identity Crystal

A synthesized snapshot of the agent's personality and state — generated from working memory, top-scored memories, and consolidation summaries. Injected at session start for continuity across context resets.

Crystals evolve. Each snapshot is preserved in history. The system can auto-generate a new crystal from workspace data via POST /v1/identity/crystallize, or you can store one manually.

Linkages

Memories can reference other memories, working memory items, or files. Linkages are stored as a JSON array on each memory:

{
  "linkages": [
    { "type": "memory", "id": "bb666a7a", "label": "supports" },
    { "type": "file", "path": "vault/reflections/day-15.md", "label": "source" },
    { "type": "item", "id": "item-abc123", "label": "tracks" }
  ]
}

Linkages enable graph traversal — following connections from one memory to discover related knowledge. See GET /v1/memories/:id/graph in the API reference.

Memory Lifecycle

Distill → Store → Embed → Score → Recall → Access → Decay → Consolidate

Distill: On context compaction, an LLM extracts novel facts, decisions, and observations from the conversation transcript and stores them automatically (tagged source:distill)
Store: Memory created with content, type, tags
Embed: Content embedded as a 384-dim vector (hosted mode, fire-and-forget)
Score: On recall, scored by keyword match × recency × access boost
Recall: Top matches returned, hybrid-ranked (keyword + semantic)
Access: Access count and timestamp updated for decay resistance
Decay: Relevance decreases exponentially (7-day half-life, runs every 6h)
Consolidate: Related memories grouped and summarized (daily, AI-powered)

Distillation bridges the gap between ephemeral conversation and persistent memory. Without it, facts discussed in conversation vanish at compaction unless the agent explicitly stores them. With it, the system automatically captures what's novel — deduplicating against existing memories — so nothing important is lost.

Workspaces

Workspaces isolate memory stores per project or agent. Each workspace gets its own edge database. Set the workspace via header:

X-Memento-Workspace: my-project

The first request with a new workspace name auto-creates everything — database, schema, default sections. No setup needed.