😸 Как улучшить работу агента с codebase-memory-mcp?
MCP codebase-memory-mcp — добротный инструментарий, позволяющий экономить тонны токенов на исследования кодовой базы и получать парой вызовов своих инструментов то, на что у агента ушли бы десятки [rip]grep, glob, read_file, etc.
Однако, в силу используемых в нём описаний инструментов, и способа интеграции с агентами, некоторым из них оказывается неочевиден воркфлоу работы с этим MCP, что приводит к ошибкам (чаще всего, связанным с идентификаторами проектов) и невозможности использовать любой из его инструментов.
Ситуацию можно исправить, если добавить в AGENTS.md проекта или агента (или в правила агента, или во что угодно, что гарантировано попадет в контекстное окно любой сессии) следующую подсказку:
## Codebase navigation via `codebase-memory-mcp` (if available)
If the `codebase-memory-mcp` MCP server is connected (e.g. its tools appear with an `[MCP]` prefix), prefer it for code discovery, call-graph tracing, and architecture questions instead of broad manual `grep`/`glob` sweeps. **Every project-scoped tool requires a project identifier.** Calling such a tool without the correct identifier returns an error of the form `project not found or not indexed` (with a hint listing the available projects).
### Project identifier
The identifier is derived from the repository's **absolute path**: replace every path separator (`/`) with `-` and drop the leading slash.
| Repository path | Project identifier |
| ----------------------------------- | ---------------------------------------- |
| `/path/to/repo` | `path-to-repo` |
`index_repository` accepts an optional `name` argument that overrides this derived identifier. **Do not set it** — it creates a separate project entry alongside the path-derived one and breaks the predictable identifier rule. Always let the identifier be derived from the path.
### Required workflow
1. **Verify the project is indexed** — call `list_projects` first (it takes no arguments). Compute the expected identifier from the repo path (rule above) and check it against the returned `projects[].name` list (or match by `root_path`).
2. **Index if absent** — if the project is missing, call `index_repository(repo_path=)` (omit `name`). Read the returned `project` field to confirm the actual identifier; it equals the path-derived form. Use `mode="fast"` for a quick pass, `"full"` when you need similarity/semantic edges.
3. **Pass the identifier to the tools** — supply it as the `project` argument to every project-scoped tool. Without it, the tool errors out and will not query the graph.
### Tools by purpose
- **Discover** — `search_graph` (BM25 + semantic + regex over functions/classes/routes), `search_code` (grep augmented by the call graph), `get_architecture` (packages, clusters, layers, hotspots).
- **Read code** — `get_code_snippet` (read a function/class by `qualified_name`; resolve it first via `search_graph`).
- **Trace relationships** — `trace_path` (callers/callees, data flow, cross-service hops), `query_graph` (raw Cypher for multi-hop/aggregate queries).
- **Change & impact** — `detect_changes` (diff vs a git ref + blast radius), `get_graph_schema` (node labels / edge types).
- **Index management** — `index_repository`, `index_status`, `list_projects`, `delete_project`, `ingest_traces` (runtime traces), `manage_adr` (Architecture Decision Records).
🙌
#ИИ_инструменты
MCP codebase-memory-mcp — добротный инструментарий, позволяющий экономить тонны токенов на исследования кодовой базы и получать парой вызовов своих инструментов то, на что у агента ушли бы десятки [rip]grep, glob, read_file, etc.
Однако, в силу используемых в нём описаний инструментов, и способа интеграции с агентами, некоторым из них оказывается неочевиден воркфлоу работы с этим MCP, что приводит к ошибкам (чаще всего, связанным с идентификаторами проектов) и невозможности использовать любой из его инструментов.
Ситуацию можно исправить, если добавить в AGENTS.md проекта или агента (или в правила агента, или во что угодно, что гарантировано попадет в контекстное окно любой сессии) следующую подсказку:
## Codebase navigation via `codebase-memory-mcp` (if available)
If the `codebase-memory-mcp` MCP server is connected (e.g. its tools appear with an `[MCP]` prefix), prefer it for code discovery, call-graph tracing, and architecture questions instead of broad manual `grep`/`glob` sweeps. **Every project-scoped tool requires a project identifier.** Calling such a tool without the correct identifier returns an error of the form `project not found or not indexed` (with a hint listing the available projects).
### Project identifier
The identifier is derived from the repository's **absolute path**: replace every path separator (`/`) with `-` and drop the leading slash.
| Repository path | Project identifier |
| ----------------------------------- | ---------------------------------------- |
| `/path/to/repo` | `path-to-repo` |
`index_repository` accepts an optional `name` argument that overrides this derived identifier. **Do not set it** — it creates a separate project entry alongside the path-derived one and breaks the predictable identifier rule. Always let the identifier be derived from the path.
### Required workflow
1. **Verify the project is indexed** — call `list_projects` first (it takes no arguments). Compute the expected identifier from the repo path (rule above) and check it against the returned `projects[].name` list (or match by `root_path`).
2. **Index if absent** — if the project is missing, call `index_repository(repo_path=)` (omit `name`). Read the returned `project` field to confirm the actual identifier; it equals the path-derived form. Use `mode="fast"` for a quick pass, `"full"` when you need similarity/semantic edges.
3. **Pass the identifier to the tools** — supply it as the `project` argument to every project-scoped tool. Without it, the tool errors out and will not query the graph.
### Tools by purpose
- **Discover** — `search_graph` (BM25 + semantic + regex over functions/classes/routes), `search_code` (grep augmented by the call graph), `get_architecture` (packages, clusters, layers, hotspots).
- **Read code** — `get_code_snippet` (read a function/class by `qualified_name`; resolve it first via `search_graph`).
- **Trace relationships** — `trace_path` (callers/callees, data flow, cross-service hops), `query_graph` (raw Cypher for multi-hop/aggregate queries).
- **Change & impact** — `detect_changes` (diff vs a git ref + blast radius), `get_graph_schema` (node labels / edge types).
- **Index management** — `index_repository`, `index_status`, `list_projects`, `delete_project`, `ingest_traces` (runtime traces), `manage_adr` (Architecture Decision Records).
🙌
#ИИ_инструменты