Memory — Persistent Context Search

What this skill does

Searches the archive index for historical context. Use when you need to find a past decision, pattern, or lesson that may have been compacted out of active memory files. Also documents when and how to write to memory.

When to use

• "What was the auth decision we made?"
• "Show me past lessons about performance"
• "Find the architecture decision for the data model"
• Any query about historical project context

When NOT to use

• For current project context (use @memory-controller load [agent] [task] instead — memory files are never read directly)
• For active decisions (use @memory-controller load [agent] [task] instead)

The memory files

When to write to memory

Write for systemic patterns only, not single-instance events:

• Write: "Tests consistently need JWT mocking — documented the pattern."
• Don't write: "Fixed a typo in auth.ts."
• Write: "API gateway times out due to unbounded connection pooling."
• Don't write: "Saw a 504 once."

Entry format strings

These are the canonical 17 domain tags (see .agents/templates/memory/memory-entry-template.md). Entries with any other tag are rejected.

Workflow

Step 0: Session start (project-context refresh)

Every agent calls this on entry, before loading context — it keeps project-context.md accurate no matter which agent is invoked ad-hoc. Run:

node .agents/scripts/orchestrator_state.js session-start --agent {agent} --domain {domain} --goal "{one-line goal}"

The mandatory complete call also refreshes project-context as a backstop, so the context updates even if session-start is skipped.

Step 1: Search archive

@memory-controller search $ARGUMENTS

Step 2: Load specific entries (optional)

Archived entries are retrieved by keyword query, not by ID — there is no load-archive [entry-id] command. To pull a specific entry, pass a distinctive phrase from it:

node .agents/scripts/memory_filter.js --search "<distinct phrase from the entry>" --max 5

This is what @memory-controller search [query] delegates to; it scans archive/index.ndjson.

Step 3: Report

Return results with title, domain tag, relevance score, summary, source, and date.

Step 4: Write to memory (on request)

@memory-controller write [entry-type] [content]

Compaction triggers

Compaction is word-based, matching .agents/scripts/compaction_guard.js (the executable source of truth) and @memory-controller's Operation 4 thresholds:

project-context.md is never compacted (static file). When a file exceeds its threshold, the oldest resolved/stale entries are archived. Archived entries remain searchable via @memory-controller search.

State machine integration

After write: node .agents/scripts/orchestrator_state.js complete --agent memory-controller --artifact {file}