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.