Memory Orchestrator

This skill is the workflow layer for the memory system. It does not replace
memory storage. It decides what to capture, where to route it, when to
promote it, and when to harden it.

Source of truth

Use this order:
1. MEMORY.md + memory/ = formal memory ledger
2. SESSION-STATE.md = current task state only
3. .learnings/ = auxiliary scratch/noise layer only
4. vector recall = derived index, never source of truth

Never create a second formal ledger.

Memory layers

1) Hot state

Use SESSION-STATE.md for:
- current task
- current blocker
- next actions
- recent decision needed for immediate continuity
- handoff / anti-compaction notes

Do not store durable history here.

2) Daily working memory

Use memory/YYYY-MM-DD.md for:
- user corrections
- task outcomes
- debugging notes
- temporary conclusions
- short self-reflection after non-trivial work
- observations that are not yet stable enough for long-term memory

3) Structured long-term memory

Route stable items to:
- memory/preferences.md — user preferences / communication style / stable likes-dislikes
- memory/system.md — stable environment facts / endpoints / toolchain constraints / paths
- memory/projects.md — long-running project context / decisions / status
- memory/MEMORY.md — cross-cutting long-term stable conclusions

4) Root summary

Use root MEMORY.md only for the few high-value facts worth automatic injection every session.
Keep it short.

5) Enforcement layer

If a recurring problem should change future behavior, also update one or more of:
- SOUL.md
- AGENTS.md
- TOOLS.md
- relevant SKILL.md
- relevant script/hook

Embedding / vector recall setup

This skill supports semantic memory search via memory_search. Multiple embedding
backends are supported. See references/embedding-setup.md for full configuration:

• Ollama (local, recommended for privacy): nomic-embed-text, mxbai-embed-large, etc.
• OpenAI Embeddings: text-embedding-3-small / text-embedding-3-large
• OpenAI-compatible APIs: LocalAI, LM Studio, third-party providers
• No embedding: Rule-based routing still works without vector recall

Quick config example (Ollama, local):

{
  "memorySearch": {
    "enabled": true,
    "provider": "ollama",
    "model": "nomic-embed-text"
  }
}

Quick config example (OpenAI):

{
  "memorySearch": {
    "enabled": true,
    "provider": "openai",
    "model": "text-embedding-3-small",
    "remote": {
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "YOUR_OPENAI_API_KEY"
    }
  }
}

First-run setup check

When this skill is triggered for the first time, or when the user asks to
"set up" / "initialize" / "check" the memory system, run this setup check:

Auto-detect missing files

Check the current workspace for these files. If any are missing, create them
from templates OR tell the user exactly which command to run:

Required files:

SESSION-STATE.md          → templates/SESSION-STATE.md
MEMORY.md                 → templates/MEMORY.md
HEARTBEAT.md              → templates/HEARTBEAT.md
memory/preferences.md     → templates/memory/preferences.md
memory/system.md          → templates/memory/system.md
memory/projects.md        → templates/memory/projects.md
memory/MEMORY.md          → templates/memory/MEMORY.md

Recommended agent files (prompt user to create if missing):

SOUL.md      — add memory discipline section (see references/setup-checklist.md Step 3)
AGENTS.md    — add memory closeout protocol
TOOLS.md     — add memory-related tool discipline

Action:
- If files are missing: create them automatically, then confirm to the user what was created.
- If agent files (SOUL.md etc.) are missing: warn the user and point to references/setup-checklist.md.
- If embedding is not configured: remind user to check references/embedding-setup.md.

One-command setup

Tell the user they can also run the setup script:

bash scripts/setup.sh [optional-workspace-path]

This will copy all templates and report what's missing.

Runtime protocol

For the concrete operating protocol, read:
- references/runtime-protocol.md

Use that reference when the memory system needs to operate reliably over time, not just route one memory item.

For setup and initialization:
- references/setup-checklist.md — step-by-step first-time setup
- scripts/setup.sh — automated setup script

For embedding setup options, read:
- references/embedding-setup.md

Routing rules

A. User says "remember this" / gives a durable preference

• Write to memory/YYYY-MM-DD.md
• If clearly stable, also write to memory/preferences.md or other structured file
• If it must shape every session, also reflect it in root MEMORY.md or enforcement files

B. Current task state changes

Before or during longer work, update SESSION-STATE.md with:
- current task
- key context
- pending actions
- blockers

Use hot state for continuity, not archiving.

C. Error / correction / better approach discovered

• Log to memory/YYYY-MM-DD.md
• If it is noisy or needs raw staging, optionally also log to .learnings/
• If recurring or broadly applicable, promote to structured memory and/or enforcement layer

D. Stable system fact discovered

• Daily first
• Then memory/system.md
• Only put in root MEMORY.md if it is worth automatic injection every session

E. Project decision / project context

• Daily first
• Then memory/projects.md
• If very stable and cross-project, also memory/MEMORY.md

Promotion / hardening state machine

Use this mental model:
- observed → captured in SESSION-STATE.md or daily
- curated → moved into structured long-term memory
- hardened → promoted into SOUL / AGENTS / TOOLS / skill / script
- stable → repeatedly validated, remains in long-term memory until marked stale

Rule:
- If the same issue appears 2+ times, or the user is clearly annoyed, do not stop at memory. Harden it.

Hygiene workflow

When asked to clean memory, adapt old memory, or audit the system:
1. Check whether old daily files contain content that already lives in structured memory
2. Add "converged/migrated/stale" style notes when appropriate
3. Ensure root MEMORY.md remains summary-only
4. Check SESSION-STATE.md is not stale or pretending to be long-term memory
5. Check .learnings/ is not drifting into primary-ledger status
6. Check recall/reference docs still point to the new architecture

When NOT to over-store

Do not promote every temporary detail.
Good memory systems are selective.
If uncertain, prefer:
- SESSION-STATE.md for immediate continuity
- memory/YYYY-MM-DD.md for tentative notes
- structured long-term only after stability is clear

Trigger phrases / situations

Use this skill when the user asks or implies any of:
- remember / save memory / note this down
- adapt old memory / migrate memory / converge old memory
- memory cleanup / memory hygiene / memory system optimization
- current task state / handoff / anti-compaction continuity
- recurring issue / repeated annoyance / make it stick
- where should this memory go?
- should this be promoted to SOUL / AGENTS / TOOLS?

Expected output style

Keep replies short.
Actually perform the routing/editing work.
Do not just say memory was saved — save it.
Do not ask for permission again when the memory action is already clear.

Reliability requirements

For non-trivial memory operations, do not stop at classification.
Make sure the system actually advances:
- update SESSION-STATE.md when current continuity matters
- update memory/YYYY-MM-DD.md for daily capture
- promote stable items to structured long-term memory
- harden recurring issues into the enforcement layer
- use the closeout protocol from references/runtime-protocol.md when a task or phase ends

If any of these are skipped, the memory system is only partially operating.