Integrates with Windsurf (by Codeium) to provide project memory tools for AI agents.
Integrates with GitHub Copilot across VS Code, CLI, and JetBrains IDEs, allowing AI agents to access persistent project memory across sessions.
Allows JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.) with the Copilot plugin to use project memory tools for reading and writing project memory.
Integrates with OpenAI Codex CLI to provide project memory tools for AI agents.
Specific integration for PyCharm IDE to use project memory via the GitHub Copilot plugin.
Specific integration for WebStorm IDE to use project memory via the GitHub Copilot plugin.
A small, local MCP server that gives AI agents (Claude Code, Cursor, VS Code / GitHub Copilot, …) a shared, persistent memory of the projects in a code folder — what each project is, decisions made, and every bug/issue faced during development.
It is stateless: every tool reads/writes plain files on disk, so multiple clients (and multiple machines) share one source of truth.
Layer | Lives in | Auto-loaded into context? | For |
Project memory |
| ✅ yes (via | identity, stack, run cmds, concise decisions/learnings — keep lean |
Issue log |
| ❌ no | high-volume bug/issue history — fetched on demand |
Design rule: durable, low-volume facts go in AGENTS.md (auto-loaded). High-volume
history (bugs) goes in issues.jsonl (queried via search_issues). This keeps the
always-loaded context small while keeping everything searchable.
Some orgs disable third-party MCP servers via policy (e.g. GitHub Copilot's MCP allowlist enforcement). Because the memory is plain files, not a service, the core value survives that:
The memory itself is just files. AGENTS.md is auto-loaded by the editor reading it —
no MCP call involved — so a project's identity, decisions, learnings, and preferences still
land in the agent's context.
The policy is Copilot-scoped and per-client. It doesn't affect the same server in
Claude Code or Cursor, and orgs running allowlist / registry-only mode can permit it —
this server is published to the official MCP Registry (io.github.kaaustubh/project-memory-mcp).
Only the interactive tools (log_issue, search_issues, …) go over the MCP channel; the
file-based memory keeps working without it.
Related MCP server: kontexta
list_projects, get_project, search_memory — read project memory
append_decision, append_learning — append a dated bullet to AGENTS.md
remember_preference — turn a correction / stated habit into a remembered pattern (## Preferences in the root AGENTS.md for a global habit, or a project's for a local one); rides the auto-load, so it comes back next session
log_issue — record a bug/problem → issues.jsonl
search_issues — "have we hit this before?" across all projects (field-scoped; optional tags filter)
list_open_issues, resolve_issue — track / close bugs
sync_registry — reconcile the root AGENTS.md projects table with what's on disk (adds rows for new projects, flags stale ones)
find_by_file — given a file path, surface the issues + decisions/learnings that touch it ("why is this code like this?")
start_initiative, get_initiative, list_initiatives, update_initiative — track a named, multi-session effort (a codename, a plan, an evolving todo list) so it's resumable from any future session by name, not just within the one that started it; see Initiatives below
You don't call these directly — you talk to your agent in natural language and it picks the tool. See Using it day to day below for what to actually say.
Most of it runs itself: opening a project auto-loads its AGENTS.md (the agent already
knows the project), and capture is proactive (plus the optional Stop hook). Your job is
mainly to pull memory at the right moments. Just talk to your agent:
When | Say something like | What fires |
Before debugging anything | "Have we hit this before? |
|
Starting something you've done elsewhere | "How did I do Stripe webhook verification in any project?" |
|
Landing on confusing code | "Why is |
|
You made a real decision / fixed a real bug | (nothing — it logs on its own and tells you) |
|
You correct how the agent works | "No, always run the typecheck before committing — remember that." |
|
Triage | "What's still open across my projects?" |
|
A bug is fixed | "Resolve pulse_stripe-004 — fixed by …" |
|
Added a new project | "Sync the registry." |
|
The one habit that matters: make "have we hit this before?" reflexive before every debugging session. That's where a memory tool earns its keep; the rest the system handles.
Capture is confirming, not silent — when the agent logs something it tells you in one line. Correct it freely: "don't log that", or "actually, log this too."
Escape hatches: PROJECT_MEMORY_HOOK=off silences the Stop hook for one session;
uninstall-hook removes it entirely.
From your code/projects folder, run:
cd ~/code # the folder that holds your projects
npx -y @kaaustubh/project-memory-mcp installThat registers the server, using the current directory as your projects root, with every client that has an MCP config location on this machine:
Client | Config written |
Claude Code | user scope, via |
Cursor |
|
VS Code / GitHub Copilot Chat | user-profile |
GitHub Copilot CLI |
|
JetBrains Copilot plugin (IntelliJ, PyCharm, WebStorm, …) |
|
Visual Studio (Windows) |
|
Kimi Code CLI |
|
Gemini CLI |
|
OpenAI Codex CLI |
|
Windsurf |
|
Each write merges into the existing file (other MCP servers you've already configured are
left alone) and is independently best-effort — a client that isn't installed on this
machine is silently skipped, the rest still get registered. Restart whichever app(s) you
use, then ask your agent "set up project memory for this folder" to scaffold AGENTS.md
for each project.
Copilot surfaces (VS Code, CLI, JetBrains, Visual Studio): tools only run in Agent mode, and config changes need a restart to take effect.
No clone, no global install — the MCP config just runs
npx, which fetches and runs the latest version on demand.
Team memory (beta signup): want this memory shared across your team instead of just your machine? Register your interest: https://github.com/kaaustubh/project-memory-mcp/issues/1
git clone https://github.com/kaaustubh/project-memory-mcp.git ~/code/.memory-server
cd ~/code/.memory-server && ./install.shA common question: "once I install it, does it just start doing things?" Not quite — the server is passive. Here's the actual flow:
Restart your editor. MCP servers are loaded at startup, so the server only becomes available the next time you launch Claude Code / Cursor / VS Code.
Push layer (automatic, not the server): when you open a project, the editor reads
AGENTS.md (via CLAUDE.md → @AGENTS.md) into the model's context for you. This is
why the agent "just knows" what your project is — it's a built-in editor feature.
Pull layer (the server, on request): the server announces its tools and then waits. It does nothing on its own. The agent calls a tool only when it's relevant — e.g. you say "log this bug" or "have we hit this before?", or the model decides a tool is useful. There's no background process or scanning.
Day one is empty. A fresh setup has no
AGENTS.mdfiles yet, so the auto-load has nothing to load andlog_issuewill refuse until a project's memory exists. Bootstrap once by asking your agent: "set up project memory for this folder" — it creates theAGENTS.mdfiles. After that, everything works.
In short: a convention (auto-loaded files) + a tool the agent chooses to use + a one-time setup. No magic, no daemon.
The server ships a standing capture policy (sent to the client on connect, plus directive tool descriptions), so the agent records things on its own instead of waiting for you to ask:
Before debugging a reported error → it checks search_issues for a prior fix.
After fixing a non-trivial bug → it calls log_issue.
After a real decision or a durable gotcha → append_decision / append_learning.
After you correct how it works or state a habit → remember_preference, so the one-time correction becomes a pattern it brings back next session.
It's proactive but not silent: the agent tells you in one line what it recorded, asks when unsure rather than logging noise, and skips trivia and secrets. You can always override — "log this", or "don't bother". The standing policy is best-effort (it depends on the model following it); for a hard guarantee, add the opt-in Stop hook below.
The standing policy can be forgotten mid-session. The Stop hook makes capture non-optional: when the agent tries to end a turn, it runs once and blocks the stop to ask for one capture pass when either (a) real work happened (file edits or a commit) and nothing was written to project memory, or (b) you corrected how it works and no preference was saved. If memory was already written, or nothing changed and you didn't correct it, the hook stays silent and lets the turn end.
npx -y @kaaustubh/project-memory-mcp install-hook # turn it on (then restart Claude Code)
npx -y @kaaustubh/project-memory-mcp uninstall-hook # turn it offOff by default — plain install does not add it; you enable it explicitly.
No loops — it fires at most once per turn (guarded by stop_hook_active), then lets
the agent stop.
Per-session kill switch — set PROJECT_MEMORY_HOOK=off to disable without uninstalling.
Cost — it adds one extra model turn only on sessions that changed code but logged nothing, or where you corrected the agent and no preference was saved; silent otherwise.
Capture is only half the loop — the other half is remembering to look. The recall hook closes it: every time you submit a prompt, it matches your request against your issue history and decisions/learnings/preferences, and silently injects the strongest hits as context. So a prior fix or decision surfaces without you (or the agent) remembering to search — the "have we hit this before?" habit becomes automatic.
npx -y @kaaustubh/project-memory-mcp install-recall # turn it on (then restart Claude Code)
npx -y @kaaustubh/project-memory-mcp uninstall-recall # turn it offSemantic matching (when available) — if the optional embeddings model
(@xenova/transformers) is installed, recall matches by meaning, so "the build is
broken" still surfaces an issue logged as "compile failure" even with no shared words.
Runs fully offline (the model is fetched once, then cached). Without it, recall falls back
to keyword matching automatically — no configuration, nothing breaks.
Silent unless relevant — injects nothing for trivial prompts or when there's no match.
Ranked & capped — current-project hits rank highest; at most 4 lines are injected.
Off by default — like the Stop hook, it's opt-in (per-prompt cost). Plain install adds
neither hook.
Per-session kill switch — set PROJECT_MEMORY_RECALL=off to disable without uninstalling.
Warm the cache: after a big logging session (or once, after enabling recall) run
npx -y @kaaustubh/project-memory-mcp reindexto pre-embed everything, so the first recall isn't the one that pays for it. Vectors are cached per project in a derived.embeddings.json(safe to delete / git-ignore — the.jsonl+AGENTS.mdstay the source of truth).
Pair it with the Stop hook and the loop runs itself: the Stop hook guarantees things get saved, the recall hook guarantees they come back at the right moment.
Decisions/Learnings capture finished facts, and issues.jsonl captures bug history —
neither has a home for a named, in-flight, multi-session effort: "give this a codename,
track the plan and todos, and let me resume it by name even in a session that's never seen
it before." That's what start_initiative / get_initiative / list_initiatives /
update_initiative are for.
you: "Let's call this HashGate. Track the plan and todos under that name."
→ start_initiative(project, codename: "HashGate", plan: "...", todos: [...])
(new session, days later)
you: "Where did we leave off on HashGate?"
→ get_initiative(project, codename: "hash gate") # case/spacing-insensitive match
you: "Continue where I left off" (no codename given)
→ list_initiatives(project) # or omit project to search everywhereEach initiative lives in its own file, <project>/initiatives/<slug>.md — a plan, a
checkbox todo list, and a dated progress log, all editable in place. A one-line pointer to
every active initiative is kept in sync under ## Active Initiatives in the project's
AGENTS.md, so a brand-new session sees what's in flight in its auto-loaded context,
with zero tool calls. Marking one done removes the pointer; the file itself stays as
history, still reachable by name.
The tool and your memory content sync separately:
Tool: nothing to sync — npx always pulls the published version (or git pull
if you installed from source).
Content: each project's AGENTS.md + issues.jsonl live inside that project's
own git repo, so cloning your projects brings their memory along. Nothing to copy.
issues.jsonlholds real bug details — only commit it into private repos.
For a new project under the root, create <project>/CLAUDE.md containing @AGENTS.md
and a <project>/AGENTS.md with ## What this is, ## Stack & layout,
## Run / build / test, ## Decisions, ## Learnings sections.
Feature: install now also registers Kimi Code CLI (~/.kimi-code/mcp.json, or
$KIMI_CODE_HOME — not to be confused with the separate "Kimi CLI" product, which uses
~/.kimi/mcp.json), Gemini CLI (~/.gemini/settings.json), and Windsurf
(~/.codeium/windsurf/mcp_config.json) — all three match the existing mcpServers/no-
type schema registerMcp already handles for Cursor, so each was a one-line addition.
OpenAI Codex CLI (~/.codex/config.toml) needed real work: it's the first non-JSON
client, configured via TOML [mcp_servers.<name>] tables. Added registerMcpToml, a
text-based find-the-table/replace-or-append merge (same spirit as appendBulletToFile's
heading match) rather than a TOML parser dependency — keeps the zero-hard-dependency
posture. Caught and fixed a real bug in it before shipping: the first version matched a
table's body as "everything up to the next literal [," which truncates mid-table
because args = [...] arrays use [ too — fixed to match "up to the next line that
starts with [" instead, verified idempotent across repeated install runs against a
pre-seeded config.toml with an unrelated table.
Feature: Initiatives. Four new tools — start_initiative, get_initiative,
list_initiatives, update_initiative — track a named, multi-session effort (a
codename, a plan, an evolving todo list) so it's resumable by name from ANY future
session, not just the one that started it. Motivated by a real failure mode reported
using another agent's session-local "codename" convention: no persistent registry
mapping name → session, todos scoped to one session's private store, and discovery
requiring an exact-string match across raw transcripts. Fixed here by storing one
markdown file per initiative (<project>/initiatives/<slug>.md — mutable, so todo
checkboxes toggle in place) plus a synced pointer under a new ## Active Initiatives
heading in the project's auto-loaded AGENTS.md, so a brand-new session sees what's in
flight with zero tool calls. Codename matching is case/spacing-insensitive (slugify
splits camelCase boundaries first, so "HashGate" and "hash gate" resolve to the same
initiative). list_initiatives searches across all projects when none is given, so
"what was I working on?" doesn't require remembering which repo it was in either.
Infra: Added a real CI workflow (.github/workflows/ci.yml, Node 18/20/22 matrix)
backed by a new stdio smoke test (scripts/smoke-test.mjs — spawns the server, does the
initialize → tools/list handshake, asserts all 12 tools register), plus a CodeQL
workflow. Both were previously entirely absent, which is why Glama's quality page showed
"CI status not available" and "No code scanning findings" — those weren't clean bills of
health, they meant "never measured."
Fix: Regenerated package-lock.json — it predated @xenova/transformers ever being
resolved with optional deps included, so npm ci failed on a clean CI runner. Also ran
npm audit fix (non-breaking), which cleared the @modelcontextprotocol/sdk-transitive
hono/body-parser/fast-uri advisories. Known issue: @xenova/transformers
(optional, powers semantic recall) still pulls in a critical + 4 high severity CVEs via
its onnxruntime-web/protobufjs/sharp chain; the only fix is a breaking downgrade to
1.4.2, deliberately not done yet — tracked as a follow-up.
Docs/meta: Added glama.json (declares maintainers) to fix Glama's "No glama.json"
profile-completion check. Paired with cutting an actual GitHub Release for this
version (previously we only pushed git tags, which Glama's "Has a release" check doesn't
see — it reads the Releases API, not tags).
Docs: Added the Glama quality-score badge to the README, per
awesome-mcp-servers's listing
requirement. Uses /badges/score.svg (a real SVG), not the plain /badge path — the
latter 200s but serves a 0-byte image/png, i.e. broken.
Feature: install now also registers GitHub Copilot CLI (~/.copilot/mcp-config.json,
or $COPILOT_HOME), the JetBrains Copilot plugin (IntelliJ/PyCharm/WebStorm/…), and
Visual Studio on Windows (global .mcp.json) — rounding out every Copilot surface
alongside the VS Code registration added in 1.7.0. Each target merges into its existing
config (other servers are preserved) and is independently best-effort, so a client that
isn't installed is silently skipped rather than failing the whole install. Schemas differ
per client (mcpServers vs servers top-level key; type: "local" for the Copilot CLI
vs type: "stdio" for the IDE-embedded ones) — verified against each client's current
docs before implementing. The merge logic for all five targets was consolidated into one
registerMcp() helper.
Feature: install now also registers the server with VS Code / GitHub Copilot
(user-profile mcp.json, so it applies to every workspace), alongside the existing
Claude Code and Cursor registration. Schema differs from Claude/Cursor (servers key,
type: "stdio" per entry) and Copilot tools only run in Chat's Agent mode.
Docs: added a team-memory beta signup note (README install section + the install
subcommand's console output) — https://github.com/kaaustubh/project-memory-mcp/issues/1
Docs: added "Works even where MCP is locked down" — clarifies that the file-based memory
(AGENTS.md auto-load) keeps working even where an org disables third-party MCP servers
(e.g. GitHub Copilot's MCP allowlist), since only the interactive tools use the MCP channel.
Semantic recall (optional local embeddings). The recall hook now matches your prompt
against memory by meaning, not shared substrings — "the build is broken" surfaces an
issue logged as "compile failure". Powered by a local, offline embedding model
(Xenova/all-MiniLM-L6-v2 via the optional @xenova/transformers dependency); vectors are
cached per project in a derived .embeddings.json, keyed by content hash so edited/removed
items self-invalidate. If the model isn't installed it falls back to the previous keyword
matching automatically — nothing to configure, nothing breaks. New reindex subcommand
pre-embeds all memory so the first recall isn't slow. This completes the long-deferred
"semantic retrieval" lever behind both recall and search_issues; keyword remains the
zero-dependency floor.
Automatic recall (opt-in UserPromptSubmit hook). New install-recall / uninstall-recall
subcommands register a hook that keyword-matches every prompt against your issue history and
decisions/learnings/preferences and silently injects the strongest hits as context — so prior
fixes and decisions surface without anyone remembering to search. Closes the other half of the
capture↔recall loop. Silent on trivial/no-match prompts (generic filler words ignored),
current-project hits ranked highest, at most 4 lines injected. Off by default; per-session kill
switch PROJECT_MEMORY_RECALL=off.
Packaging: add the mcpName field (io.github.kaaustubh/project-memory-mcp) required to list
the server in the official MCP Registry. No functional change.
remember_preference — corrections become remembered patterns. New tool that writes a
dated bullet under ## Preferences, either in the root AGENTS.md (scope global —
applies to every project) or a single project's. Because preferences live in the
auto-loaded AGENTS.md, recall is free: a one-time correction ("never add a co-author
trailer", "always typecheck before committing") comes back next session and is applied
instead of re-corrected. Closes the cross-session loop for how you like to work, not just
project facts.
Correction-aware Stop hook + capture policy. The standing policy now nudges
remember_preference after a correction, and the opt-in Stop hook scans the session for
behavioural-correction phrases ("from now on…", "no, don't…", "always use…"): if you
corrected the agent and no preference was saved, it blocks the stop once to ask — a second,
independent reason alongside the existing "code changed but nothing logged" check.
Docs: added a "Using it day to day" section — the natural-language prompts that map to each tool, the one habit that matters ("have we hit this before?"), and the escape hatches. Clarifies that you talk to the agent rather than calling tools directly.
Stop hook: count direct memory edits as capture. The hook previously recognized only
mcp__project-memory__* tool calls, so editing AGENTS.md / issues.jsonl directly
(an endorsed capture path) still triggered the nag. It now also treats an Edit/Write
to a file ending in AGENTS.md or issues.jsonl as captured — eliminating the false
positive.
append_decision/append_learning: no more duplicate sections. Heading matching was
whole-line (^## Learnings$), so a heading with trailing text (## Learnings (gotchas …))
wasn't found and a duplicate section got appended. Now matches the heading's leading word.
Guaranteed capture (opt-in Stop hook). New install-hook / uninstall-hook
subcommands register a Claude Code Stop hook that forces a single capture pass when a
session changed code but recorded nothing to memory — turning the best-effort policy into
a hard guarantee. Off by default, fires at most once per turn (no loops), silent when
nothing changed or memory was already written, and disablable per-session via
PROJECT_MEMORY_HOOK=off.
Sharper issue search. search_issues now matches only the text fields
(symptom/cause/fix/id/tags) instead of the raw JSON, so queries no longer get false hits
on field names. Added an optional tags filter; query is now optional (search by tags
alone).
sync_registry. Reconciles the root AGENTS.md projects table with the projects on
disk — adds stub rows for projects missing from the table, flags rows whose directory is
gone, and reports live open-issue counts. Automates the previously manual "new project →
add a row" step. Hand-curated columns are preserved; apply=false reports drift only.
find_by_file. Given a file path/fragment, returns the issues (via their files
field) and the decisions/learnings (via AGENTS.md bullets that mention it) touching that
file — code↔memory linking for "why is this code the way it is?".
Docs only: publishes the changelog to the npm page for parity (no functional change).
Proactive capture. The agent now records memory on its own instead of waiting for
"log this": a standing capture policy is sent on initialize and the write/search tool
descriptions are directive. It stays confirming (tells you what it logged), asks when
unsure, and skips trivia/secrets. Explicit calls still work as an override.
Docs: added "How it works (after install)" and "Proactive capture" sections.
Fix npx … install failing with "command not found" — the bin is renamed to
project-memory-mcp to match the unscoped package name (npx resolution rule).
Initial release: stateless MCP server over AGENTS.md + issues.jsonl, 9 tools
(project memory + issue tracking), npx … install for Claude Code and Cursor, and the
push/pull memory model.
Append a dated bullet under '## Decisions' in a project's AGENTS.md (auto-loaded memory). Call this PROACTIVELY right after a non-obvious or architectural decision is made — don't wait to be asked — then tell the user in one line what you recorded. For concise, durable decisions and WHY; not bugs (use log_issue) and not trivia.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | One line: the decision and WHY, not just what. | |
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that it modifies AGENTS.md, appends under a specific section, and records decisions with WHY. However, it omits details about error handling, idempotency, or what happens if the section doesn't exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that front-load the action and location. Every sentence provides useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no nested objects, no output schema), the description covers all essential aspects: what it does, when to use it, what not to use it for, and how to record decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%. Description adds meaningful guidance for 'text' (one line, decision and WHY, not just what). For 'project', no additional context, but it's a straightforward identifier. The description compensates for the missing schema description on 'text'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool appends a dated bullet under '## Decisions' in AGENTS.md. It specifies the verb (append) and resource (project's AGENTS.md), and differentiates from siblings like log_issue and append_learning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to call proactively after non-obvious/architectural decisions, not for bugs or trivia, and instructs to inform the user. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a dated bullet under '## Learnings' in a project's AGENTS.md (auto-loaded memory). Call this PROACTIVELY when you discover a durable gotcha/workaround future sessions should know — don't wait to be asked — then tell the user what you recorded. For a specific bug use log_issue instead.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. It discloses that the tool modifies AGENTS.md (auto-loaded memory) and that the action is proactive, plus instructs to inform the user. Lacks details on idempotency or side effects, but adequate for a simple append.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should mention return behavior. It doesn't state what the tool returns or if it creates the file if missing. Could be more complete regarding preconditions and outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters. It implies 'text' is the learning content and 'project' is the identifier, but does not provide explicit format or constraints. Acceptable given simplicity of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool appends a dated bullet under '## Learnings' in AGENTS.md. Distinguishes from sibling log_issue by specifying that this is for general learnings, not specific bugs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to call proactively upon discovering durable gotchas/workarounds, and provides an alternative for specific bugs (log_issue). No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Given a file path or filename fragment, return the issues (matched via their 'files' field) and the decisions/learnings (matched via AGENTS.md bullets that mention it) that touch that file — i.e. 'why is this code the way it is?' answered from memory. Searches all projects unless one is given. Useful when you land on confusing code and want the history behind it.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | A path or filename fragment, e.g. 'index.js' or 'auth/login'. | |
| project | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses search scope (all projects or specified), matching criteria (via 'files' field for issues, AGENTS.md bullets for decisions/learnings). Could mention it's read-only, but intent is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. Action and context are front-loaded. Every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains input parameters and output types (issues, decisions/learnings). No output schema, but description covers what is returned. Could mention pagination or limits, but not critical for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 50% (file param described). Description adds value for project param by stating default behavior ('searches all projects unless one is given') and clarifies file param usage with examples. Compensates for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns issues and decisions/learnings that touch a given file, answering 'why is this code the way it is?'. It distinguishes from siblings like search_memory or log_issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when you land on confusing code and want the history behind it') and mentions scope ('searches all projects unless one is given'). Does not explicitly list alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full plan/todos/progress log for one named initiative by codename (case/spacing-insensitive — 'hash gate' matches 'HashGate'). Call this PROACTIVELY at the start of a session when the user references resuming a specific named effort. If the codename doesn't resolve, lists that project's known initiatives instead of erroring blindly.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| codename | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the case/spacing-insensitivity of codename matching and the fallback behavior on unresolved codename. However, it does not mention authorization or rate limits, but given it's a read operation, the transparency is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each purposeful. First defines core function, second gives usage advice, third describes error handling. No wasted words, information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description hints at return content ('full plan/todos/progress log') and covers the case of invalid codename. It is sufficiently complete for a get-by-key tool, though it could specify whether the return is a single object or may include nested items.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds meaning to both parameters: 'codename (case/spacing-insensitive)' and indirectly explains 'project' through the fallback mention ('lists that project's known initiatives'). It could be improved by explicitly describing the project parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch the full plan/todos/progress log') and the resource ('one named initiative by codename'). It distinguishes from sibling tools like list_initiatives by focusing on a single initiative and mentions the fallback behavior that lists project initiatives, which differentiates its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to call the tool ('PROACTIVELY at the start of a session when the user references resuming a specific named effort') and what to expect if the codename doesn't resolve ('lists that project's known initiatives instead of erroring'). This helps the agent decide between get_initiative and list_initiatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full AGENTS.md memory for one project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project directory name, e.g. pulse_stripe |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It only states what the tool does but omits any details about performance, side effects, error conditions, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the tool's function with no wasted words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one well-documented parameter, the description is largely complete. The return value is hinted ('full AGENTS.md memory'), but there is no mention of error handling or confirmation that the returned data format is intuitive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100% for the single parameter. The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Return') and specifies the resource ('full AGENTS.md memory') with a qualification ('for one project'), effectively distinguishing it from sibling tools like list_projects and search_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as search_memory or get_initiative. There are no hints about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List named initiatives (codename, status, last updated) across one project or — if project is omitted — ALL projects, most-recently-updated first. Call this PROACTIVELY when the user references resuming past work ('continue X', 'where were we on Y') WITHOUT stating an exact codename or which project, instead of guessing or searching blindly.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| project | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that listing can span all projects if project is omitted, returns specific fields, and sorts by most recent update. It does not explicitly state it's read-only, but the verb 'list' implies non-destructive behavior. Could mention rate limits or pagination, but adequate for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence explains functionality concisely; the second provides a specific usage scenario. Front-loaded with the key capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 2 parameters and no output schema, the description covers the main behavior, filtering by project, sorting, and proactive use. However, it does not explain the status parameter, pagination, or result limits. It gives enough to use the tool but misses some details that would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no descriptions in schema). The description mentions 'project' and 'status' implicitly but does not explain their purpose or constraints. For example, the 'status' parameter is an enum (active, paused, done) but the description never indicates that it filters results by status. The description fails to compensate for the lack of schema descriptions, leaving the agent to infer parameter semantics from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'initiatives'. It specifies the output fields (codename, status, last updated) and the scope: across one project or all projects if omitted. This distinguishes it from siblings like get_initiative (single) and list_projects (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to call this proactively when the user references resuming past work without an exact codename or project. This provides clear when-to-use guidance and implicitly suggests alternatives like get_initiative for known codenames or searching blindly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List unresolved issues across all projects (or one).
| Name | Required | Description | Default |
|---|---|---|---|
| project | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as side effects (none expected), pagination, sorting, or error handling. It is minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the key information. It could be slightly expanded without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations, output schema, and minimal parameters, the description is adequate but lacks details on return behavior or edge cases. It is minimally complete for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context to the optional 'project' parameter by explaining it can be used to filter by a single project or omitted for all projects. However, schema coverage is 0%, and the description does not provide additional details like value format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'unresolved issues', and the scope 'across all projects (or one)'. It effectively distinguishes from sibling tools like 'search_issues' and 'get_project'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing open issues but does not explicitly state when to use this tool over alternatives like 'search_issues'. It provides no guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects under ~/code that have an AGENTS.md memory file.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description indicates read-only listing, but lacks details on side effects, authentication, rate limits, or return format. Simple operation but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no wasted words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, yet description does not specify return structure (e.g., list of project names, paths). Incomplete for a tool with no schema to fall back on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no parameters (100% coverage). Description adds value by explaining the filtering criterion (projects under ~/code with AGENTS.md), going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (list), resource (projects), and specific scope (under ~/code that have an AGENTS.md memory file). Distinguishes from sibling tools like get_project and search_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly suggests use when wanting to enumerate projects with memory files, but no explicit guidance on when not to use or alternatives (e.g., get_project for a single project).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a structured bug/issue to /issues.jsonl (high-volume memory, NOT auto-loaded). Call this PROACTIVELY whenever you resolve (or get blocked by) a non-trivial bug — don't wait to be asked — then tell the user in one line what you logged. Skip trivial/transient issues.
| Name | Required | Description | Default |
|---|---|---|---|
| fix | No | How it was fixed, if resolved. | |
| tags | No | ||
| cause | No | Root cause, if known. | |
| files | No | ||
| status | No | Defaults to 'resolved' if a fix is given, else 'open'. | |
| project | Yes | ||
| symptom | Yes | What went wrong / the observable failure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the log is appended to a file, high-volume memory, and NOT auto-loaded. Without annotations, it carries the full burden; it adds useful context about when to use and performance implications, though could mention more about mutation safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loaded with the core action and clear usage guidance; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides essential usage context and proactive behavior, but lacking parameter explanations and return value info; no output schema exists. Still adequate for the agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 57%, the description adds no parameter details beyond 'structured bug/issue'. It does not explain fields like project, symptom, or status; the description could have compensated but didn't.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool appends a structured bug/issue to a file, distinguishing it from sibling tools that search or resolve issues. The verb 'log' and resource 'bug/issue' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Call this PROACTIVELY whenever you resolve (or get blocked by) a non-trivial bug — don't wait to be asked'; also instructs to skip trivial/transient issues and to inform the user in one line.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a dated bullet under '## Preferences' in an AGENTS.md (auto-loaded memory), turning a user correction or stated habit into a remembered pattern that comes back next session. Call this PROACTIVELY when the user corrects HOW you work or states a durable preference — code style, workflow habit, a 'from now on' rule (e.g. 'never add a co-author trailer', 'always run the typecheck before committing') — don't wait to be asked, then tell the user in one line what you saved. Use scope 'global' (root AGENTS.md, applies to EVERY project) for a cross-project habit; scope 'project' for a preference about one project. This is about agent behaviour/preferences; for a project DECISION use append_decision, for a bug use log_issue.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The preference as a durable rule, ideally with a short WHY. Phrase it as guidance for next time, not a one-off. | |
| scope | No | 'global' = root AGENTS.md (every project). 'project' = one project. Defaults to global, unless only a project is given. | |
| project | No | Required when scope is 'project'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that it modifies AGENTS.md, explains scope behavior, and states it is about agent behavior/preferences. It does not mention destructive side effects or permissions, but it is largely transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that is well-structured and front-loaded with the main action. Every sentence earns its place, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, no output schema), the description covers when to use, what to do, scope, and sibling differentiation. It provides sufficient context for correct invocation, though details like date format are omitted (minor).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining phrasing requirements ('durable rule, ideally with a short WHY'), scope distinction, and when the project parameter is required. This goes beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool appends a dated bullet under '## Preferences' in AGENTS.md, turning user corrections into remembered patterns. It explicitly distinguishes from siblings like append_decision and log_issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: call proactively when the user corrects how you work or states a durable preference, and tell the user what was saved. It also contrasts with siblings: 'for a project DECISION use append_decision, for a bug use log_issue'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an issue resolved and record the fix.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Issue id, e.g. pulse_stripe-003 | |
| fix | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only mentions 'resolve' and 'record the fix' without disclosing side effects, required permissions, or state changes. For a state-changing tool, more behavioral context is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose. No unnecessary words. Efficiently communicates the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or return value description. For a simple tool with two parameters, the description is adequate but could mention what the response looks like or if the issue is closed/updated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: 'id' has a schema description with example, 'fix' lacks one. The tool description adds 'record the fix' which gives context for the 'fix' parameter, partially compensating for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (mark an issue resolved) and the resource (issue), and includes the specific detail of recording the fix. It distinguishes from sibling tools like 'log_issue' which creates issues, and 'search_issues' which searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites or when not to use it. Implied usage from description, but no explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search bug/issue history across all projects (or one) over the TEXT FIELDS only (symptom, cause, fix, id, tags) — not the raw JSON, so you won't get false hits on field names like 'fix' or 'status'. Optionally filter by tags (issue must carry all of them). Either query or tags may be given. Call this PROACTIVELY when the user reports an error or you hit a familiar-looking failure, BEFORE debugging from scratch, to check for a prior fix ('have we hit this before?').
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Only return issues carrying ALL of these tags. | |
| query | No | Text to match against symptom/cause/fix/id/tags. | |
| project | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains search scope (text fields only, avoiding false hits) and optional tag filtering. This is good behavioral context for a search tool. Could mention return format or pagination but not essential.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph with front-loaded purpose. Concise with no wasted sentences, though could be broken into shorter sentences for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description explains what is searched but not the return format. Includes proactive usage advice. Fairly complete for a search tool given sibling tools are not directly comparable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (query and tags described, project not). Description clarifies query matches specific fields and tags require all. Adds value but does not cover the 'project' parameter, leaving its meaning ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies it searches bug/issue history over specific text fields (symptom, cause, fix, id, tags) across all projects or one, clearly distinguishing from raw JSON search. The verb 'search' and resource 'issue history' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to call this proactively when a user reports an error or familiar failure, before debugging, to check for prior fixes. Provides context for when to use but does not list alternatives (e.g., other sibling tools) for not using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Case-insensitive search across every project's AGENTS.md. Returns matching lines with their project.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It states case-insensitive search and returns lines with project, implying read-only operation. However, no mention of permissions, rate limits, or edge cases like empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load key information. No redundant or extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with one parameter and no output schema, the description covers scope (all projects' AGENTS.md), behavior (case-insensitive), and output (matching lines with project). Missing minor details like return format for no matches but still adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description only briefly refers to 'query' as search term without elaborating on format, constraints, or examples. Adds minimal value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool performs case-insensitive search across every project's AGENTS.md and returns matching lines with project context. It is specific and distinct from sibling tools like search_issues which search issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like search_issues. Usage is implied for searching project memory but lacks when-not-to-use or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start tracking a named, multi-session effort under a codename — a plan plus an evolving todo list stored in /initiatives/.md, with a pointer kept in the project's auto-loaded AGENTS.md under '## Active Initiatives' so a BRAND NEW session sees it's in flight without calling any tool. Call this PROACTIVELY when the user names a multi-step effort with a codename or asks you to 'track this as X' / 'remember this under the name X' — don't wait to be asked. If the codename already exists, returns the existing initiative unchanged (safe to call again on a resumed session) rather than overwriting progress.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | Yes | The plan/analysis for this effort. | |
| todos | No | Initial todo items, if known. | |
| project | Yes | ||
| codename | Yes | A short memorable name, e.g. 'HashGate'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses file creation, AGENTS.md modification, idempotency, and non-overwrite behavior. However, it does not mention potential side effects like need for project existence or file permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
All sentences are valuable, but the description is a single dense paragraph. Front-loading is good, but could be more structured with bullet points for readability. Still concise given the detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core behavior and usage, but lacks mention of return value or error handling. Without output schema, description should hint at what the tool returns. Also does not specify prerequisites like project existence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (3 of 4 parameters have descriptions). The description adds meaning for 'codename' and 'plan', but does not elaborate on 'project' beyond what schema implies. Still adds value by explaining storage location and use of codename.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to start tracking a multi-session effort by creating a file and updating AGENTS.md. It distinguishes itself from sibling tools like get_initiative, list_initiatives, and update_initiative by explaining its proactive usage and idempotency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to call this tool proactively (when user names a multi-step effort with a codename) and when it's safe to recall (if codename exists, returns unchanged). Also contrasts with waiting for explicit request.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reconcile the root AGENTS.md projects table with what's actually on disk: list projects that have an AGENTS.md but no table row (and add a stub row for each), flag rows whose directory no longer exists, and show live open-issue counts. Automates the 'new project → add a row' step so the cross-project index never silently drifts. Hand-curated columns (Stack, Status, descriptions) are preserved — stubs use the project's '## What this is' line and leave Stack/Status as '?'. Set apply=false to report drift without writing.
| Name | Required | Description | Default |
|---|---|---|---|
| apply | No | Write stub rows for new projects (default true). false = report only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that it adds stub rows, preserves hand-curated columns, can report-only with apply=false, and uses the project's description. However, it does not explicitly state whether it modifies existing rows or what happens to flagged missing directories beyond 'flagging'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that front-loads the main purpose. It is somewhat dense and contains minor redundancy (e.g., restating the automation of the 'new project' step), but overall it is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 parameter, no output schema), the description covers the purpose, process, and parameter effectively. It hints at output (open-issue counts, flagged missing directories) but does not provide a specific format, which is acceptable for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'apply' is well-described in the schema, and the description adds contextual guidance on its usage. Schema coverage is 100%, so baseline is 3; the description's extra context modestly enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'reconcile' and the resource 'root AGENTS.md projects table', detailing the actions: listing projects, adding stub rows, flagging missing directories, and showing open-issue counts. It effectively distinguishes itself from sibling tools like list_projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a specific use case (automating the 'new project → add a row' step) and explains when to use the apply parameter to report without writing. It does not explicitly exclude alternative tools, but the context implies this is for reconciliation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a named initiative: append a dated progress-log line, add new todos, check off completed todos (matched by case-insensitive substring against existing unchecked items), and/or change status. Call this PROACTIVELY as todos complete or real progress happens — not just at session end — then tell the user in one line what you recorded. Setting status to 'done' removes its pointer from AGENTS.md's Active Initiatives (the file itself is kept as history, still reachable via get_initiative/list_initiatives).
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| project | Yes | ||
| codename | Yes | ||
| progress | No | A line to append to the progress log (dated automatically). | |
| add_todos | No | ||
| complete_todos | No | Substrings matching existing unchecked todo lines to check off. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully covers behavioral aspects: automatic date logging for progress lines, case-insensitive substring matching for completing todos, and the side effect of removing the pointer from AGENTS.md when status is 'done'. These details are crucial for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but packs multiple instructions into a few sentences. It is front-loaded with the purpose and uses clear action verbs. Minor improvements could include bullet points for readability, but it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no output schema, no annotations), the description covers the key behavioral aspects and usage guidance. It lacks explicit return value or error details, but for an update tool, the provided information is sufficient for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context beyond the schema: 'progress' is dated automatically, 'complete_todos' uses substring matching against unchecked items, and status 'done' triggers removal of the pointer. Schema coverage is only 33%, so the description compensates effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a named initiative and lists four specific actions: appending a progress log, adding todos, checking off completed todos, and changing status. It is easily distinguishable from sibling tools like `start_initiative` and `get_initiative`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to call the tool proactively as progress happens, not just at session end. It also explains the effect of setting status to 'done'. While it does not explicitly mention when not to use it or name alternatives, the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct action and resource type: projects, memory entries, issues, initiatives, registry, and file-to-memory linking. No two tools have overlapping purposes.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_projects, append_decision, sync_registry). No mixing of styles or vague verbs.
With 16 tools, the count is slightly above the ideal range but still well-scoped for a project memory system covering projects, issues, initiatives, and registry management.
The tool set covers full lifecycle: listing/reading projects, searching/appending memory entries, CRUD for issues, full initiative management, registry sync, and file-referenced memory lookups. No obvious gaps.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
An MCP server that gives your AI access to the source code and docs of all public github repos
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kaaustubh/project-memory-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
