Empirical Memory

View saved version →

---
name: empirical-memory
description: Use Empirical to recall/save durable project context across sessions and projects, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.
---

# Empirical Memory (MCP mode)

Use Empirical to carry durable context across projects and clients, and as the first stop for
"how do I use Empirical" questions — command syntax, install/auth/workspace/kit/skill setup, or
what Empirical can do. Don't answer those from general knowledge or by guessing: use the
`memory_usage_guide` MCP tool for the current, agent-readable answer first.

This variant is for installs where the user chose MCP as their integration mode. The connected
Empirical MCP server is the primary and expected way to reach Empirical here — use its tools
directly, not `empirical` CLI commands, as the first move.

**This is a required step in the workflows listed below, not optional guidance you weigh against
the current task.** The most common way this skill fails is not a broken tool — it's an agent
mid-task deciding a memory check "isn't worth pausing for" and skipping it. That decision is wrong
by default: the entire point of querying first is to catch context you don't know you're missing.
If you are not sure whether a task qualifies, treat it as if it does.

## Before doing work — MUST, not discretionary

1. Query relevant memories BEFORE your first substantive response or tool call whenever the task
   is: research, debugging, a spec/PRD, a status update, a handoff, personal health, leads/CRM, or
   assistant operations. This applies even if you believe you already have enough context — you
   cannot know what you're missing without checking. Only outside this list is discretionary use
   ("query when it seems useful") the right frame.
2. If you have not used Empirical's MCP tools yet this session, call `memory_usage_guide` once to
   confirm current tool names, filters, and pagination behavior before relying on memory.
3. Use the `query_memories` MCP tool for recall. Use filters such as `category`, `tags`,
   `nodeType`, and `monthKey` when they improve recall. For "recent/latest/today" requests, prefer
   `list_memories` instead — it is the tool built for that shape of request. For exhaustive topic
   retrieval, use the topic as a tag and follow pagination.
4. A slow response alone is API latency, not an outage; report an outage only when a tool call
   returns an actual error, and use `get_empirical_policy` or a retry to verify connectivity before
   escalating.
5. A filtered `query_memories` call (`category`, `tags`, `nodeType`) that returns nothing is not
   proof the memory doesn't exist — it only proves nothing matched that exact filter combination.
   A memory's real category or tag convention often does not match how you or the user would
   naturally describe it in conversation (e.g. described as "an idea" but stored under a
   different category; tagged with a project's short name where you tried its full one). Before
   concluding a memory doesn't exist, retry at least once with the filter relaxed or removed —
   category dropped, tags loosened to an OR match, or a plain unfiltered query — rather than only
   varying the search phrase.
6. If a specific recall miss turns out to have a narrow, demonstrable cause (a filter mismatch, a
   stale tag, a wrong category), stop there. Report that cause and move on — do not generalize one
   miss into a theory about the memory system being broken and then go build measurement or
   debugging work around the theory. Confirm the narrow cause is insufficient before entertaining a
   systemic explanation, not after.

## Follow the current user policy

The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
change without reinstalling this plugin. Read it when the skill activates:

1. Use the read-only `get_empirical_policy` MCP tool.
2. If policy lookup fails, use safe defaults: preserve durabl

Preview of the first 4,000 characters. Read full instructions →