Institutional memory search — one question, everything you already know

What this is for

Before an agent guesses, assumes, or rebuilds something from scratch, it should check whether the answer already exists: a past decision, a written intent, a commit that explains why, a tool that already does this. A single search across all of that — rather than five separate lookups, or none — is what this skill is about.

There are two ways to get it, and you should know which one you're running before you trust the results:

If institutional memory search is set up (optional — see /alignment-harness:harness-setup)

The author's own setup calls this tool agent_find, backed by a local MCP server (agent-swarm) that indexes several kinds of source in one place and returns a single ranked list:

agent_find("firebase email spam")

Two-path search runs on every query:

1. Semantic (primary) — embeds the query with a local model (no external API call) and runs cosine similarity against every indexed source. Catches synonyms and paraphrases ("cost model" finds "pricing philosophy").
2. Keyword (fallback) — substring/regex matching, for exact matches and anything not yet in the vector index (commits, plain docs).

Results merge, get scored by relevance × sourceWeight × recencyDecay, and are deduped by title.

What can feed it, if you've wired the source up (several of these are their own skills in this plugin — intent-db, agentic-tooling-registry, and your own memory log):

Source	What it is	Needs
Memory log	Structured notes from past sessions (decisions, corrections, lessons)	a JSONL log you or a hook write to
Intent records	Written statements of why something was built and what it should achieve	intent-db skill + a database
Registered tools	Your own scripts/endpoints, described so they're findable instead of rebuilt	agentic-tooling-registry
Markdown docs	Your repo's own documentation	just git
Git commits	Commit history and messages	just git
Tasks / work items	Whatever tracker you use	your own integration

Recency decay (a reasonable starting default, tune to your own volume): e^(-0.012 × daysAgo) — today=1.0, 7d≈0.85, 30d≈0.6, 90d≈0.35. Source weights are also starting defaults — retune them once you have real query history (see agentic-find-how-to-optimize-monthly-maintenence-only if you build that habit).

When the index is empty or thin (a fresh install with nothing indexed yet), say so plainly: "no institutional memory yet — 0 sessions indexed" is the honest answer. A confident-looking empty result and a broken tool look identical to whoever's reading your output; don't let a genuine zero pass as a confirmed absence of prior work.

When MCP is down ("Transport closed")

The pipe is dead for this session — don't retry the MCP call. Use whatever CLI fallback your setup shipped (the author's: node <path-to-agent-swarm-mcp>/scripts/agent-find-cli.js "your query"), tell the person the transport is down and a restart will restore it, and keep working with the local fallback below in the meantime.

If it isn't set up (works everywhere, no setup)

Claude Code already keeps a durable record of your own history — you don't need a search server to check whether something was already decided:

1. Grep your own past sessions: grep -l "<keyword>" ~/.claude/projects/*/*.jsonl — each session's full transcript, including your corrections (the clearest statement of your actual intent), lives there.
2. Search the repo's own docs and notes: grep -ril "<keyword>" docs/ README.md CLAUDE.md (or wherever your project keeps them).
3. Check git history: git log --all --oneline --grep="<keyword>" and git log -p --all -S"<keyword>" for when something changed and why.
4. Say plainly when nothing turns up. "No prior record found on this — proceeding fresh" costs nothing and keeps you honest; presenting fresh reasoning as if it confirmed a past decision does not.

This costs a few seconds instead of one MCP call, and it never silently fails — grep either finds a match or it doesn't.

When to use

• Starting any non-trivial task — check first.
• Before writing a new helper or script — something similar may already exist.
• Debugging — find related past decisions or fixes.
• Understanding intent — surface why something was built, not just what it does.

When NOT to use

• For a specific known file path → use Glob.
• For code inside a known file → use Grep.
• To log a new memory or decision → write it to your memory log (or alignment-harness records <kind> if you haven't set one up).

Is it set up / is it working?

• With institutional memory search: run a query on something you know is indexed — does the right thing come back near the top, and does it say honestly when the index is thin?
• Without it: does grep -l "<keyword>" ~/.claude/projects/*/*.jsonl find the right session? That's your whole test — no server to keep alive.