| name | agentmemory-codebase-recall |
| description | Structured protocol for using agentmemory as a recall layer during codebase investigation. Load when any agent would otherwise start with broad Read/Grep/Glob exploration. agentmemory accelerates orientation — it is NOT a substitute for reading current source files.
|
| use-when | Load when an agent begins investigation and may benefit from prior session context on
the same system. Load for recall of earlier bug fixes, design decisions, or failed
approaches in the current project.
|
| do-not-use-when | Do not load when the task involves a completely new system with no prior work.
Do not use as a substitute for reading current source files — memory is a hint, not ground truth.
|
| platforms | ["claude-code","codex","copilot","cursor","windsurf"] |
| metadata | {"source":"internal","version":"1.0.0","tier":1,"user-invocable":false} |
| task-categories | ["memory","recall","codebase-navigation"] |
agentmemory Codebase Recall
This is a skill pack, not an agent. Load it when triage indicates prior sessions exist
for the touched system, or when an investigation, bug-fix, or feature task would benefit
from prior architectural knowledge.
Core Contract
agentmemory is a recall layer. It is NOT the source of truth.
Current repo files always win. Memory surfaces candidate files, known pitfalls, and
architectural decisions from prior sessions. Every memory hit must be verified against
the actual file before being acted on.
| Principle | Meaning |
|---|
| Recall before exploration | Query memory before opening files or running Grep |
| Verify before using | Read the current file; memory may be stale |
| Files win on conflict | If memory contradicts current source → trust the file |
| Never edit from memory alone | A memory fact is a hypothesis; code read confirms it |
| Never claim from memory alone | Do not assert architecture facts without file evidence |
Mandatory Flow
agentmemory query
│
▼ candidate files / symbols / known pitfalls
targeted file discovery (Read, Grep on known paths only)
│
▼ current source text
verify memory against files
│
▼ confirmed facts only
analyze / edit / implement
│
▼ after task completes
save findings (mcp__agentmemory__memory_lesson_save or memory_save)
Do NOT skip to "targeted file discovery" without first running the memory query.
Do NOT skip the "verify against files" step even if memory looks confident.
Tool Reference
The following tools are confirmed present in this project's MCP configuration.
Do NOT invent tool names — use only these.
Note: The canonical source for the agentmemory MCP server capabilities is
https://github.com/rohitg00/agentmemory — verify tool names against current docs
if the list below ever diverges from actual MCP responses.
Query tools (use BEFORE opening files)
| Tool | When to use |
|---|
mcp__agentmemory__memory_smart_search | First call — natural-language search across all sessions. Pass the symptom, system name, or component name. |
mcp__agentmemory__memory_recall | Direct recall by tag or session ID when you know the exact context. |
mcp__agentmemory__memory_sessions | List prior sessions to find relevant context when smart_search returns nothing useful. |
Save tools (use AFTER task completes)
| Tool | When to use |
|---|
mcp__agentmemory__memory_lesson_save | Save a structured lesson: root cause, fix, detection signal, affected systems. Preferred for bug fixes and architecture decisions. |
mcp__agentmemory__memory_save | Save raw notes, scratch, or partial findings when a full lesson isn't appropriate. |
Maintenance tools (use only when directed)
| Tool | When to use |
|---|
mcp__agentmemory__memory_reflect | Summarise or re-index a session's memories. Run when a session accumulated many unstructured saves. |
mcp__agentmemory__memory_consolidate | Merge duplicate or redundant memories. Run when prior sessions produced overlapping lessons. |
mcp__agentmemory__memory_diagnose | Check agentmemory health, index integrity, or connection issues. |
Query Discipline
Step 1 — Smart search first
mcp__agentmemory__memory_smart_search(
query: "<symptom or system name>",
tags: ["<domain>", "<component>"] // optional — improves recall precision
)
Good queries: component names (HealthComponent), system names (DamageSystem),
symptoms ("ECB dropped dependency"), patterns ("structural change in job").
Bad queries: generic terms ("bug", "Unity", "system").
Step 2 — Interpret results
Each memory hit has a confidence score. Apply this policy:
| Confidence | Treatment |
|---|
| High (≥ 0.80) | Use as strong candidate — still verify in file |
| Medium (0.50–0.79) | Use as weak hint — read file before trusting |
| Low (< 0.50) | Note but do not prioritise — likely stale or out-of-context |
Step 3 — Targeted file discovery
Use memory output to form specific Read/Grep targets:
- "memory says
DamageSystem.cs owned HealthComponent writes" → Read DamageSystem.cs
- "memory warns about dropped Dependency in
WeaponSystem" → grep for state.Dependency in WeaponSystem.cs
Do NOT issue broad Glob("**/*.cs") or Read-all-in-folder after memory returns results.
Unavailability Fallback
If any mcp__agentmemory__* call fails with a connection error or the server is unreachable:
- Report
[MEMORY UNAVAILABLE] once in your output.
- Do NOT retry in a loop.
- Fall back to targeted repo search — Grep known symbol names, Read specific files
from triage / approved_plan. No random exploration.
- If this is a bug investigation: note the gap in
workspace/investigation.md:
"Prior session recall unavailable — investigation proceeds from code evidence only."
Save Discipline
After completing a task, save one lesson per non-obvious finding. Quality gate:
Save if:
- Root cause was not obvious from a single file read
- A DOTS pitfall was discovered (Dependency drop, ECB singleton mismatch, Burst error)
- An architecture decision was made that future agents should know
- A component ownership boundary was clarified or changed
Do NOT save if:
- The fix was ≤ 3 lines and self-explanatory from the code
- The finding repeats something already in
workspace/repo-knowledge.md verbatim
- The session produced only read-only investigation with no confirmed conclusions
Lesson format for memory_lesson_save
lesson: "In <project>: <symptom> → root cause: <SystemName>.<field/component>.
Fix: <what changed>. Detection: <signal to look for>."
tags: ["<system-area>", "<domain>", "<component-name>"]
Example (generic — substitute your project's name and system names):
lesson: "In <project>: enemies stop moving after area transition → root cause:
MovementSystem drops state.Dependency when CombatSystem schedules first.
Fix: combine handles with JobHandle.CombineDependencies.
Detection: profile job overlap in frame after transition."
tags: ["movement", "ecs", "dependency-chain", "combat"]
DOTS-Specific Recall Hints
When querying memory for a DOTS bug or feature, always include these recall probes
if the standard smart_search returns low-confidence results:
| Probe | Why it matters |
|---|
"update order <SystemName>" | Prior ordering decisions are invisible in code; memory captures them |
"ECB playback <system group>" | Wrong ECB singleton is a common silent bug |
"state.Dependency <SystemName>" | Dropped dependency produces no error — only stale reads |
"component ownership <ComponentName>" | Dual ownership surfaces here before it surfaces in tests |
"Burst error <job name>" | Burst failures are often project-specific type mismatches |
"IEnableableComponent <ComponentName>" | Toggles vs add/remove decisions are architectural |
"ComponentLookup update <SystemName>" | Stale lookup is a common oversight after refactor |
"NativeContainer lifetime <SystemName>" | Disposal gaps only appear under domain reload or scene change |
"Schedule ScheduleParallel <JobName>" | Parallelism decisions carry hidden constraints |
Self-Check Before Moving to Implementation
Anti-Patterns
- Opening broad file lists before querying memory
- Trusting a 6-month-old memory fact without re-reading the file
- Skipping memory because "I already know this system"
- Saving every trivial read as a lesson (noise bloat)
- Using
memory_consolidate or memory_reflect during an active investigation (maintenance ops, not investigation ops)
