/codebase-memory-mcp

name: codebase-memory-mcp
description: Resolve canonical Git checkouts, index and verify codebase-memory-mcp graphs through the guarded CLI, open its browser viewer on request, and safely audit duplicate worktree caches. Use when a user mentions codebase memory MCP, dependency graphs, search_graph, trace_path, index_repository, worktree indexes, or oversized graph caches.
license: MIT
metadata:
  source: "https://github.com/vincentkoc/dotskills"

Codebase Memory MCP

Purpose

Bring up `codebase-memory-mcp` for the owning Git checkout and prove the graph is usable before relying on it for code discovery. Keep linked worktrees on the owner's graph instead of creating one graph per branch.

When to use

• Initialize, re-index, refresh, or troubleshoot a repository graph.
• Use `search_graph`, `trace_path`, `get_code_snippet`, or `query_graph`.
• Verify that a repository is indexed before graph-backed exploration.
• Open the existing dependency graph in a browser when requested.
• Audit or prune duplicate linked-worktree indexes without deleting cache files directly.

Workflow

1. Verify the repository and binary.

• `git rev-parse --show-toplevel`
• `git status -sb`
• `command -v codebase-memory-mcp`
• `codebase-memory-mcp --version`

2. Resolve the canonical owning checkout.

• `scripts/codebase-memory-graph.sh canonical --repo "$(git rev-parse --show-toplevel)"`
• Linked worktrees resolve through their absolute Git common directory to the one checkout that owns it.
• Separate clones remain separate projects.
• Independent roots under `~/.codex/worktrees`, `~/GIT/_Worktrees`, any `.worktrees` component, `/tmp`, or `/private/tmp` are never indexed. Linked worktrees under those paths may only rewrite to one existing nonreserved owner.
• Never independently index `~/GIT/_Synthetic` or repositories marked by `.git/gwt-synthetic.json`. This indexing rule grants no cleanup authority.
• Missing, invalid, bare, ambiguous, ownerless, reserved-owner, or NUL-containing repositories fail closed.

3. Prefer exposed MCP graph tools for discovery.

• If the tool is absent, the service times out/closes its transport, or no usable project exists, report that surface once and continue ordinary code work with bounded `rg` and direct reads. Do not retry without changed service evidence. Graph availability is not a prerequisite for ordinary inspection or repair.
• Installer or client configuration must separately disable the MCP `index_repository` tool because it cannot enforce the canonical indexing boundary. For Codex installs, render the private `disabled_tools` configuration accordingly.
• When indexing is requested and the graph is missing, run `scripts/codebase-memory-graph.sh index --repo "$(git rev-parse --show-toplevel)" --mode full`. Do not start indexing or daemon repair as an incidental prerequisite to another task.
• Use `search_graph`, `trace_path`, and `get_code_snippet` before broad text scans.

4. Use the helper for CLI indexing.

• `scripts/codebase-memory-graph.sh init --repo "$(git rev-parse --show-toplevel)" --mode full`
• The helper always sends the canonical owning checkout to `index_repository`.
• Use `--mode fast` for a smoke index.
• Installer integrations render `scripts/codebase-memory-gateway.py.tmpl` with an approved pinned backend path. Replace `@@PYTHON_PATH_SHEBANG@@` with the raw absolute interpreter path and replace `@@PYTHON_PATH_JSON@@`, `@@BACKEND_PATH_JSON@@`, and `@@RESOLVER_PATH_JSON@@` with JSON string literals containing the exact absolute interpreter, backend, and `codebase_memory_cache.py` paths. The rendered gateway has no upgrade logic and uses `execve` for pass-through.
• The gateway guards raw CLI calls only. Zero-argument MCP stdio startup intentionally passes through to the approved backend, so the gateway is not an MCP tool-filtering proxy and does not replace the separate `disabled_tools` control.
• The public CLI accepts a tool name and at most one JSON object. It normalizes `--json` and `--progress` before checking `index_repository`; index calls always require an explicit JSON `repo_path`. File, stdin, worker, prefixed-command, and vendor-installer forms fail closed. Default output and explicit `--json` output keep their upstream formats.
• Installation defaults are `auto_index=false`, `auto_watch=false`, and `ui_enabled=false`. Ordinary MCP/CLI calls do not enable the viewer or reset an operator's explicit setting. Initialize the UI default with `codebase-memory-mcp config set ui_enabled false`; `ui` is not a supported backend config key.
• Ordinary MCP clients share one session-managed daemon. Bare `daemon start` remains denied because it implicitly enables the UI. The explicit browser command `daemon start --open [--port=N]` is allowed; `daemon status` remains read-only.

5. Verify the graph.

• `codebase-memory-mcp cli list_projects`
• `scripts/codebase-memory-graph.sh schema --repo "$(git rev-parse --show-toplevel)"`
• Run one focused graph query before declaring success.

6. Open the viewer only when requested.

• `scripts/codebase-memory-graph.sh start-ui --repo "$(git rev-parse --show-toplevel)"` resolves the owner, enables the viewer, and uses native `daemon start --open`. It does not index or create tmux sessions.
• The preference is shared and persists across daemon restarts. Ordinary loading leaves it unchanged, so another agent cannot close an explicitly opened viewer. A fresh installation starts with it off.
• `scripts/codebase-memory-graph.sh stop-ui` restores `ui_enabled=false` without stopping the shared daemon or other sessions. Closing a browser tab alone does not disable the listener.
• Use the guarded CLI helper for indexing; the browser's indexing endpoint does not enforce this skill's Git-owner/worktree policy. Opening an existing graph does not authorize indexing additional roots.

7. Audit cache cleanup before applying it.

• Freeze a h