remember
Store project-specific conventions, decisions, and failures with reasons to build a persistent codebase memory that guides future development.
Instructions
Routes to the active/current project automatically when known. CALL IMMEDIATELY when user explicitly asks to remember/record something.
USER TRIGGERS:
"Remember this: [X]"
"Record this: [Y]"
"Save this for next time: [Z]"
DO NOT call unless user explicitly requests it.
HOW TO WRITE:
ONE convention per memory (if user lists 5 things, call this 5 times)
memory: 5-10 words (the specific rule)
reason: 1 sentence (why it matters)
Skip: one-time features, code examples, essays
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Type of memory being recorded. Use "failure" for things that were tried and failed - prevents repeating the same mistakes. | |
| category | Yes | Broader category for filtering | |
| memory | Yes | What to remember (concise) | |
| reason | Yes | Why this matters or what breaks otherwise | |
| scope | No | Optional scope for this memory. Use { kind: "file", file } or { kind: "symbol", file, symbol }. | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Implementation Reference
- src/memory/store.ts:112-122 (helper)appendMemoryFile helper: reads existing memories from file, checks for duplicates by ID, appends the new memory if not duplicate, and writes back to disk.
export async function appendMemoryFile( memoryPath: string, memory: Memory ): Promise<{ status: 'added' | 'duplicate'; memory: Memory }> { const existing = await readMemoriesFile(memoryPath); const found = existing.find((m) => m.id === memory.id); if (found) return { status: 'duplicate', memory: found }; existing.push(memory); await writeMemoriesFile(memoryPath, existing); return { status: 'added', memory }; } - src/memory/store.ts:226-240 (helper)buildMemoryIdentityParts helper: constructs a deterministic string from memory fields (type, category, memory, reason, scope) used as input for SHA-256 hashing to generate a content-based ID.
export function buildMemoryIdentityParts(memory: { type: MemoryType; category: MemoryCategory; memory: string; reason: string; scope?: MemoryScope; }): string { const scopePart = !memory.scope || memory.scope.kind === 'global' ? 'global' : memory.scope.kind === 'file' ? `file:${normalizePathLike(memory.scope.file)}` : `symbol:${normalizePathLike(memory.scope.file)}:${memory.scope.symbol}`; return `${memory.type}:${memory.category}:${memory.memory}:${memory.reason}:${scopePart}`; } - src/memory/store.ts:31-54 (helper)normalizeMemoryScope helper: validates and normalizes the optional scope argument (global, file, or symbol) for the remember tool.
export function normalizeMemoryScope(raw: unknown): MemoryScope | undefined { if (!isRecord(raw)) return undefined; const kind = raw.kind; if (kind === 'global') { return { kind }; } if (kind === 'file' && typeof raw.file === 'string' && raw.file.trim()) { return { kind, file: normalizePathLike(raw.file.trim()) }; } if ( kind === 'symbol' && typeof raw.file === 'string' && raw.file.trim() && typeof raw.symbol === 'string' && raw.symbol.trim() ) { return { kind, file: normalizePathLike(raw.file.trim()), symbol: raw.symbol.trim() }; } return undefined; }