Improve agent protocol: peek-then-drill, concrete write triggers, mul…#2
Improve agent protocol: peek-then-drill, concrete write triggers, mul…#2
Conversation
…ti-point recall - Rewrite README workflow: two-phase recall (peek brief → drill get), recall trigger table (6 moments), write trigger table (6 types), end-of-task writes - Update MCP tool descriptions to reinforce peek-then-drill pattern: memory_recall emphasizes format=brief first, memory_get is the drill step, memory_add lists concrete trigger points - Address real agent behavior problems: agents reading body on broad queries, only recalling at session start, not knowing when to write memories
There was a problem hiding this comment.
Pull request overview
This PR updates the AI Memory Protocol guidance to encourage a consistent “peek-then-drill” recall workflow and to clarify concrete moments when agents should write new memories.
Changes:
- Rewrites the README workflow into a two-phase recall process (peek brief → drill get) with explicit recall/write trigger tables.
- Updates MCP tool descriptions (
memory_recall,memory_get,memory_add) to reinforce the same usage pattern and writing triggers.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| src/ai_memory_protocol/mcp_server.py | Updates MCP tool descriptions to guide agents toward brief recall first, then targeted gets, and more explicit add triggers. |
| README.md | Expands the recommended workflow section with two-phase recall guidance plus recall/write trigger tables and updated context-window optimization bullets. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "Get full details of a specific memory by ID. " | ||
| "Always shows body text. Use after recall to drill into a specific memory." | ||
| "Get full details of a specific memory by ID — the DRILL step. " | ||
| "Always shows body text. Use AFTER memory_recall(format='brief') to read " |
There was a problem hiding this comment.
memory_recall(format='brief') is Python-call syntax; MCP callers provide JSON arguments. Reword to align with actual tool invocation (e.g., “after calling memory_recall with format=brief”) so the guidance is unambiguous.
| "Always shows body text. Use AFTER memory_recall(format='brief') to read " | |
| "Always shows body text. Use AFTER calling memory_recall with format=brief to read " |
| | Session start | `recall --format brief --limit 20 --sort newest` | | ||
| | New task or topic | `recall --tag topic:<X> --format brief` | | ||
| | Entering unfamiliar code | `recall --tag repo:<X> --type fact --format brief` | | ||
| | Before a design decision | `recall --tag topic:<X> --type dec` | | ||
| | When stuck or debugging | `recall <error keywords>` | | ||
| | Before implementing a pattern | `recall --tag intent:coding-style --type pref` | |
There was a problem hiding this comment.
In this table the examples use recall ... without the memory CLI prefix (and without the MCP tool name memory_recall). As written, these commands won’t work in the shell and are inconsistent with the rest of the README; please change them to memory recall ... (or explicitly label them as MCP tool invocations).
| | Session start | `recall --format brief --limit 20 --sort newest` | | |
| | New task or topic | `recall --tag topic:<X> --format brief` | | |
| | Entering unfamiliar code | `recall --tag repo:<X> --type fact --format brief` | | |
| | Before a design decision | `recall --tag topic:<X> --type dec` | | |
| | When stuck or debugging | `recall <error keywords>` | | |
| | Before implementing a pattern | `recall --tag intent:coding-style --type pref` | | |
| | Session start | `memory recall --format brief --limit 20 --sort newest` | | |
| | New task or topic | `memory recall --tag topic:<X> --format brief` | | |
| | Entering unfamiliar code | `memory recall --tag repo:<X> --type fact --format brief` | | |
| | Before a design decision | `memory recall --tag topic:<X> --type dec` | | |
| | When stuck or debugging | `memory recall <error keywords>` | | |
| | Before implementing a pattern | `memory recall --tag intent:coding-style --type pref` | |
| | Entering unfamiliar code | `recall --tag repo:<X> --type fact --format brief` | | ||
| | Before a design decision | `recall --tag topic:<X> --type dec` | | ||
| | When stuck or debugging | `recall <error keywords>` | | ||
| | Before implementing a pattern | `recall --tag intent:coding-style --type pref` | |
There was a problem hiding this comment.
This row also uses recall ... without the memory prefix/tool name. For consistency (and copy/paste correctness), change to memory recall --tag intent:coding-style --type pref (or memory_recall if these are MCP calls).
| | Before implementing a pattern | `recall --tag intent:coding-style --type pref` | | |
| | Before implementing a pattern | `memory recall --tag intent:coding-style --type pref` | |
| - Use `--limit 10` when exploring broad topics | ||
| - Use `--expand 0` to skip graph expansion for exact matches only | ||
| - `recall` omits body by default — this is intentional, not a limitation | ||
| - **Peek** with `--format brief` → **drill** with `get <ID>` — this is the core pattern |
There was a problem hiding this comment.
In “drill with get <ID>” the command is missing the memory prefix (elsewhere you use memory get ...). Consider changing to memory get <ID> so readers can copy/paste the command and it stays consistent with the CLI reference.
| - **Peek** with `--format brief` → **drill** with `get <ID>` — this is the core pattern | |
| - **Peek** with `--format brief` → **drill** with `memory get <ID>` — this is the core pattern |
| "Search memories by free text query and/or tags. " | ||
| "Returns matching memories formatted for context windows. " | ||
| "Use this FIRST to check existing knowledge before starting work." | ||
| "Use format='brief' FIRST to peek at titles, then memory_get to drill into specific IDs. " |
There was a problem hiding this comment.
The description uses Python-style format='brief' wording, but MCP tool calls are JSON inputs. Consider rephrasing to match the schema (e.g., “call memory_recall with format set to brief”) to avoid clients interpreting it as code/CLI syntax.
| "Use format='brief' FIRST to peek at titles, then memory_get to drill into specific IDs. " | |
| "First, call this tool with the \"format\" field set to \"brief\" to peek at titles, then call memory_get to drill into specific IDs. " |
1 participant
…ti-point recall