/echo

name: echo
description: "Use when the user references past sessions, asks 'what did we do', 'do you remember', 'last session', 'recall', or 'continue from'."
version: 1.0.0

🔊 Echo: Searching the Archives...

*Recall information from past CC sessions using semantic vector search.*

Activation

When this skill activates, output:

`🔊 Echo: Searching the archives...`

Then execute the protocol below.

Context Guard

| Context | Status | Priority | |---------|--------|----------| | **User says "recall", "remember", "last session", "what did we"** | ACTIVE: search memory | P1 | | **User asks about past work explicitly ("did we build X?")** | ACTIVE: search memory | P1 | | **User says "continue from" or "resume" a past topic** | ACTIVE: search memory | P2 | | **User is describing NEW work to do ("build X", "add Y")** | DORMANT, this is new work, not recall | none | | **User mentions "memory" in code context (RAM, variables)** | DORMANT, technical term, not MemStack recall | none | | **User mentions a project name in present tense ("work on X")** | DORMANT, forward-looking, not recall | none | | **User says "save" or "log" (Diary/Project territory)** | DORMANT, Diary or Project skill handles writing | none |

Anti-Rationalization

If you're thinking any of these, STOP, you're about to skip the protocol:

| You're thinking... | Reality | |---|---| | "I remember this from earlier in the conversation" | You don't persist. Earlier context may be compacted. Run the search. | | "I can just summarize from what I know" | You know nothing from prior sessions. The database does. Search it. | | "The user probably doesn't need exact details" | Users ask Echo for specifics: dates, decisions, file paths. Run all steps. | | "Vector search seems slow, I'll skip to SQLite" | Vector search returns the best results. Always try it first. | | "I found one result, that's probably enough" | Run ALL steps (vector + SQLite + insights). One source misses context another catches. | | "The keywords are too vague to search" | Search anyway. Vague queries still return useful semantic matches. |

Protocol

Step 1: Semantic Vector Search (primary)

Try LanceDB vector search first for best-quality results:

python "$MEMSTACK_PATH/skills/echo/search.py" "<keywords>" --top-k 5

If this returns results, present them with scores, dates, and source files.

Step 2: SQLite Keyword Search (augment or fallback)

Always run SQLite search to supplement vector results or as fallback if Step 1 fails:

python "${CLAUDE_PLUGIN_ROOT}/db/memstack-db.py" search "<keywords>" --project <project>

Step 3: Recent Sessions and Insights

For additional context:

python "${CLAUDE_PLUGIN_ROOT}/db/memstack-db.py" get-sessions <project> --limit 5
python "${CLAUDE_PLUGIN_ROOT}/db/memstack-db.py" get-insights <project>

Step 4: Markdown Fallback

If both vector and SQLite return nothing, check `memory/sessions/` and `memory/projects/` for markdown files.

Step 5: Present Findings

Combine and deduplicate results from all sources:

• **Vector results**: Show with similarity scores and section headings
• **SQLite results**: Show with dates and accomplishment summaries
• **Source attribution**: Always show which source (vector/SQLite/markdown) each result came from
• Date and project name
• What was accomplished
• What was left pending
• Key decisions and insights

Step 6: No Results

If nothing found across all sources, say clearly: "No session logs found for [topic]. Use Diary to save future sessions."

Indexing

To re-index sessions after new diary entries (normally done automatically):

python "$MEMSTACK_PATH/skills/echo/index-sessions.py"

Use `--force` to re-embed all content (e.g., after changing embedding model):

python "$MEMSTACK_PATH/skills/echo/index-sessions.py" --force

Embedding provider

Echo uses LOCAL embeddings by default: sentence-transformers (`all-MiniLM-L6-v2`, 384-dim). No API key is needed and nothing leaves the machine.

OpenAI embeddings (`text-embedding-3-small`, 1536-dim) are strictly OPT-IN. Enable them either way:

• set `MEMSTACK_EMBED_PROVIDER=openai` in the environment (also requires an `OPENAI_API_KEY` to be set), or
• pass `--provider openai` to the indexer.

A bare `OPENAI_API_KEY` in the environment does NOT switch Echo to OpenAI on its own; the opt-in above is required. An explicit OpenAI opt-in with no key present is a hard error, not a silent downgrade to local, so an index is never built with a provider you did not choose.

Switching providers requires a `--force` re-index, because the vector dimensions differ (local 384 vs OpenAI 1536) and the two cannot be mixed in one index. Search automatically matches whatever provider the current index was built with (recorded in `metadata.json`).

Inputs

• Keywords from the user's prompt (project name, feature name, date range)
• Vector DB: `$MEMSTACK_PATH/memory\vectors\lancedb\` (via LanceDB)
• Database: `~/.memstack/memstack.db` (via memstack-db.py)
• Fallback: `$MEMSTACK_PATH/memory\` (legacy markdown files)

Outputs

• Ranked results with semantic similarity scores
• Source type attribution (vector, database, or markdown fallback)
• Summary of relevant past session context

Example Usage

**User:** "Do you remember what we did on AdminStack last session?"

🔊 Echo: Searching the archives...

Vector search (top 3):
  [1] AdminStack: 2026-02-18 (session)
      Section: Accomplished
      Score: 0.912
      Built CC Monitor page with session cards, auto-refresh, notifications.
      Created /api/cc-sessions CRUD + public report endpoint.

  [2] AdminStack, 2026-02-17 (session)
      Section: Decisions
      Score: 0.847
      Used SWR for auto-refresh instead of polling. API key via HMAC-SHA256.

  [3] AdminStack: 2026-02-18 (session)
      Section: Next Steps
      Score: 0.791
      Deploy dashboard, add notification preferences, test mobile view.

SQLite