Pin or unpin a memory
memory_pinIdempotent
Toggle the pinned status of a memory to protect it from pruning and boost its search ranking. Pin only high-leverage facts and decisions; overuse diminishes effectiveness.
Instructions
Toggle the pinned flag — pinned memories survive pruning and rank higher in search. Idempotent. Use sparingly: reserve pins for canonical decisions, user preferences, and high-leverage facts. Pinning everything defeats the purpose.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | Id of the memory to pin or unpin. | |
| pinned | No | `true` (default) to pin, `false` to unpin. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | `Memory <id> pinned.` / `Memory <id> unpinned.` on success, `Memory <id> not found.` when missing. |
Implementation Reference
- src/tools/memory-pin.ts:3-14 (handler)Handler function that pins or unpins a memory by calling repo.setPinned(). Returns a human-readable result string.
export async function handleMemoryPin( repo: MemoriesRepo, params: { memory_id: string; pinned: boolean }, ): Promise<string> { const ok = repo.setPinned(params.memory_id, params.pinned); if (!ok) { return `Memory not found: ${params.memory_id}`; } return params.pinned ? `Memory pinned: ${params.memory_id}` : `Memory unpinned: ${params.memory_id}`; } - src/index.ts:578-581 (schema)Input schema: memory_id (required string) and pinned (optional boolean, default true).
inputSchema: { memory_id: z.string().min(1).describe("Id of the memory to pin or unpin."), pinned: z.boolean().default(true).describe("`true` (default) to pin, `false` to unpin."), }, - src/index.ts:589-591 (schema)Output schema: returns a message string.
outputSchema: { message: z.string().describe("`Memory <id> pinned.` / `Memory <id> unpinned.` on success, `Memory <id> not found.` when missing."), }, - src/index.ts:570-594 (registration)Tool registration with MCP server under the name 'memory_pin'.
server.registerTool( "memory_pin", { title: "Pin or unpin a memory", description: [ "Toggle the pinned flag — pinned memories survive pruning and rank higher in search. Idempotent.", "Use sparingly: reserve pins for canonical decisions, user preferences, and high-leverage facts. Pinning everything defeats the purpose.", ].join(" "), inputSchema: { memory_id: z.string().min(1).describe("Id of the memory to pin or unpin."), pinned: z.boolean().default(true).describe("`true` (default) to pin, `false` to unpin."), }, annotations: { title: "Pin or unpin a memory", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, outputSchema: { message: z.string().describe("`Memory <id> pinned.` / `Memory <id> unpinned.` on success, `Memory <id> not found.` when missing."), }, }, async (params) => textResult(await handleMemoryPin(memRepo, params)) ); - src/db/memories.ts:298-300 (helper)Helper method on MemoriesRepo that delegates to update() to set the pinned field in the database.
setPinned(id: string, pinned: boolean): boolean { return this.update(id, { pinned }); }