cm-continuity

Continuity — Working Memory Protocol

TL;DR

• Use at session start (read) and end (update)
• File: .cm/CONTINUITY.md (working memory)
• Auto-loads: recent learnings from .cm/learnings.jsonl
• Loki Mode: prevents repeating past mistakes

Context persistence across sessions. Mistakes captured. Learnings applied.

Inspired by Loki Mode's CONTINUITY.md protocol (Autonomi).

When to Use

ALWAYS — This is a background protocol, not an explicit invocation.

• Start of every session: Read .cm/CONTINUITY.md to orient yourself
• End of every session: Update .cm/CONTINUITY.md with progress
• On error: Record in Mistakes & Learnings section
• On key decision: Record in Key Decisions section

Setup

Prerequisite: The cm CLI is the CodyMaster command-line tool. If not installed, you can

manage .cm/CONTINUITY.md directly with your editor or the AI agent without the CLI commands.

# Initialize working memory for current project
cm continuity init

# Check current state
cm continuity status

# View captured learnings / decisions
cm continuity learnings
cm continuity decisions

# ── Smart Spine v5 commands ──────────────────────────────
# Regenerate L0 compact indexes (learnings-index.md, skeleton-index.md)
cm continuity index

# Show token budget allocation + usage per category
cm continuity budget

# Pretty-print current context bus state (active skill chain)
cm continuity bus

# Print Codex Desktop MCP config snippet for cm-context server
cm continuity mcp

# Migrate learnings.json + decisions.json → SQLite (one-time)
cm continuity migrate

# Export SQLite back to JSON (backup)
cm continuity export

# ── Legacy config note ────────────────────────────────────
# CodyMaster's supported default path is SQLite + FTS5.
# Older configs may still say `storage.backend: viking`; CodyMaster now warns and falls back to SQLite.

The Protocol

AT THE START OF EVERY SESSION:

1. Read .cm/CONTINUITY.md to understand current state
2. Read "Mistakes & Learnings" to avoid past errors
3. Check "Next Actions" to determine what to do
4. Reference Active Goal throughout your work

DURING WORK:

PRE-ACT ATTENTION CHECK (before every significant action):
  - Re-read Active Goal
  - Ask: "Does my planned action serve this goal?"
  - Ask: "Am I solving the original problem, not a tangent?"
  - If DRIFT detected → log it → return to goal

AT THE END OF EVERY SESSION:

1. Update "Just Completed" with accomplishments
2. Update "Next Actions" with remaining work
3. Record any new "Mistakes & Learnings"
4. Record any "Key Decisions" made
5. Update "Files Modified" list
6. Set currentPhase and timestamp

ON ERROR (Self-Correction Loop):

ON_ERROR:
  1. Capture error details (stack trace, context)
  2. Analyze root cause (not just symptoms)
  3. Write learning to CONTINUITY.md "Mistakes & Learnings"
  4. Update approach based on learning
  5. Retry with corrected approach
  6. Max 3 retries per error pattern before ESCALATE

CONTINUITY.md Template

# CodyMaster Working Memory
Last Updated: [ISO timestamp]
Current Phase: [planning|executing|testing|deploying|reviewing]
Current Iteration: [number]
Project: [project name]

## Active Goal
[What we're currently trying to accomplish — 1-2 sentences max]

## Current Task
- ID: [task-id from dashboard]
- Title: [task title]
- Status: [in-progress|blocked|reviewing]
- Skill: [cm-skill being used]
- Started: [timestamp]

## Just Completed
- [Most recent accomplishment with file:line references]
- [Previous accomplishment]
- [etc — last 5 items]

## Next Actions (Priority Order)
1. [Immediate next step]
2. [Following step]
3. [etc]

## Active Blockers
- [Any current blockers or waiting items]

## Key Decisions This Session
- [Decision]: [Rationale] — [timestamp]

## Mistakes & Learnings

### Pattern: Error → Learning → Prevention
- **What Failed:** [Specific error that occurred]
- **Why It Failed:** [Root cause analysis]
- **How to Prevent:** [Concrete action to avoid this in future]
- **Timestamp:** [When learned]
- **Agent:** [Which agent]
- **Task:** [Which task ID]

## Working Context
[Critical information for current work — architecture decisions, patterns being followed.
⚠️ NEVER store API keys, secrets, or credentials here — use .env or a secrets manager instead]

## Files Currently Being Modified
- [file path]: [what we're changing]

Memory Architecture (v5 — Smart Spine)

Tier 1: SENSORY MEMORY (seconds — within current tool call)
  → Internal variables, intermediate results
  → NEVER written to file — discarded when action completes

Tier 2: WORKING MEMORY (current session → 7 days)
  → CONTINUITY.md — the active scratchpad (max 500 words / ~400 tokens)
  → Auto-rotates: entries > 7 days promote to Tier 3 or decay
  → Context bus (.cm/context-bus.json) — live skill chain state
    · initBus() on chain start, updateBusStep() on each advance
    · cm://pipeline/current resolves to bus JSON
    · Read via: cm continuity bus | cm_bus_read MCP tool

Tier 3: LONG-TERM MEMORY (30+ days, only if reinforced)
  → Default:  .cm/context.db (SQLite + FTS5)
      · learnings table + learnings_fts (BM25 keyword search)
      · decisions table + decisions_fts
      · skill_outputs per session/chain
      · indexes table (cached L0/L1 content + staleness hash)
  → Legacy config note: `storage.backend: viking` now falls back to SQLite
      · True vector semantic search — finds "async timeout" even when you query "network delay"
      · L0/L1/L2 auto-generated by engine — no manual cm continuity index needed
      · Session compression + long-term memory extraction built-in
      · Graph relations between memories (link/unlink)
      · No separate OpenViking setup remains in the supported runtime
  → Fallback: .cm/memory/learnings.json + decisions.json (kept for compat)
  → L0 indexes: .cm/learnings-index.md (~100 tok), .cm/skeleton-index.md (~500 tok)
      · Auto-regenerated on addLearning() + on demand via cm continuity index
      · File watcher auto-refreshes learnings L0 on JSON change (300ms debounce)
      · With Viking: engine generates L0/L1 automatically — no file watcher needed
  → Token budget: .cm/token-budget.json — 200k window, per-category soft limits
      · Enforced at load time: checkBudget() → allowed/remaining/suggestion
      · View: cm continuity budget

Tier 4: EXTERNAL SEMANTIC MEMORY (optional — large projects)
  → tobi/qmd — BM25 + Vector + LLM re-ranking, 100% local
  → See cm-deep-search skill — ONLY when >50 docs or >200 source files

Tier 5: STRUCTURAL CODE MEMORY (optional — code-heavy projects)
  → CodeGraph — tree-sitter AST → SQLite graph → MCP server
  → See cm-codeintell skill — ONLY when >50 source files

CONTINUITY.md = "what am I doing NOW?" context bus = "what did upstream skills produce in this chain?" L0 indexes = "cheapest possible memory load (~600 tokens)" context.db = "keyword search across all learnings + decisions" Legacy viking config = "compatibility fallback to SQLite, not a separate backend" qmd (optional) = "find what was written across hundreds of docs"

MCP Context Server (Codex Desktop, Goose, and any MCP client)

Fifteen tools exposed over stdio — start with cm mcp-serve:

# Start MCP server (stdio)
cm mcp-serve --project /path/to/project

# Print config snippet for Codex Desktop or Goose
cm mcp-serve --print-config

| Tool | Purpose | Since | |---|---|---| | cm_query | FTS5 keyword search — learnings, decisions, or both | v4.5 | | cm_resolve | Load any cm:// URI at L0/L1/L2 depth | v4.5 | | cm_bus_read | Read live context bus state | v4.5 | | cm_bus_write | Publish skill output to the bus | v4.5 | | cm_budget_check | Pre-flight token check by category | v4.5 | | cm_memory_decay | Archive expired learnings (supports dry_run) | v4.5 | | cm_index_refresh | R