Context Service

Agents have limited context windows. The Context Service provides three layers of memory — persistent vault, ephemeral scratchpad, and active context management — so agents can remember across sessions and work efficiently within token budgets.

Overview

Every agent operates within a finite context window. Without memory management, agents forget everything when the session ends and lose important details when context fills up and compacts. The Context Service solves this with three complementary systems:

Crystal Vault — permanent knowledge that persists across sessions
Scratchpad — working notes that survive both context compaction and session restarts
Context Management — curate, evict, and query what's loaded in the active window

Crystal Vault

The vault is an agent's long-term memory. Entries persist across sessions and survive context compaction. When an agent discovers something important — an architectural decision, a bug pattern, a configuration quirk — it writes to the vault.

Vault Operations

Command	Description
`vault_write`	Save an insight with optional keywords for retrieval
`crystal_search`	Search entries by keyword (returns top matches)
`crystal_read`	Read full entry body by ID (e.g. crys-003)
`crystal_list`	List all entries with pagination
`crystal_edit`	Update an entry's body or metadata
`crystal_delete`	Delete an entry (audit-logged)

# Write a persistent insight

<vault_write keywords="rate-limit,cascade,timeout">API rate limits cascade into agent timeouts</vault_write>

# Response:

Created entry crys-042

# Search for relevant insights

<crystal_search query="rate limit"/>

# Results:

[crys-042] API rate limits cascade into agent timeouts

[crys-103] 429 errors cause wasted agent cycles

Automatic Nudging

The system automatically surfaces relevant vault entries when the conversation matches entry keywords. You don't need to manually search every time — if an agent is working on rate limiting and has a vault entry about rate limits, the system nudges it into context.

Scratchpad

The scratchpad is for temporary working notes. It survives context compaction (so you don't lose your train of thought mid-task) and persists across sessions: notes are stored at vault_dir/scratchpad.md and loaded back on rebirth.

Command	Description
`scratchpad`	Overwrite scratchpad with new content
`scratchpad_append`	Add content to existing scratchpad
`scratchpad_get`	Read current scratchpad contents
`scratchpad_clear`	Wipe the scratchpad

# Save current task notes

<scratchpad>session 5 — working on auth refactor. 3 files remaining.</scratchpad>

# Append new finding

<scratchpad_append>found bug in login.py line 42</scratchpad_append>

# Read it back

<scratchpad_get/>

Vault vs Scratchpad: Use the vault for discoveries you want to keep forever (architectural decisions, bug patterns). Use the scratchpad for tracking what you're doing right now (current task, temporary notes, reminders).

Context Management

The active context window is finite. When it fills up, the system automatically compacts older content into summaries. Agents manage what stays and what goes by emitting XML tags.

The /context Command

The /context command manages the context service ledger from your side: /context show displays the current ledger, /context evict <ctx_id> [reason] evicts a ledger entry, /context stats shows ledger statistics, and /context clear clears the ledger (history is untouched).

Command	Description
`curate`	Replace verbose content with a summary (or mark to keep)
`evict`	Remove content from context entirely
`context_query`	Check what's currently loaded in context

# Summarize heavy content you've already processed

<curate id="large-file-read" decision="summary">Config file with 3 sections: db, auth, cache</curate>

# Check what's in context

<context_query>what files have I read?</context_query>

# Remove something you no longer need

<evict id="old-analysis-output">analysis phase finished</evict>

The Three Layers

Layer	Scope	Survives
Crystal Vault	Permanent knowledge	Sessions + compaction
Scratchpad	Temporary working notes	Sessions + compaction
Context Window	Active conversation	Neither (auto-compacted)

Cross-Agent Memory

Each agent has its own vault and scratchpad. The hub also provides tools to inspect other agents' memory:

hub_vault — view another agent's vault summary
hub_vaults — list all agent vaults across the mesh

This enables the coordinator to understand what each agent knows and make better task assignment decisions.

Next Steps

1
The Hub
Where agents communicate and coordinate.
2
Discovery & Identity
How agents find and identify each other.