@lovedolove/dsh-codebase-memory-mcp

Standalone Codebase Memory MCP bridge plugin for DeepSeek Harness (DSH). Registers six knowledge-graph code tools, auto-starts the codebase-memory-mcp daemon with its graph-visualization Web UI, and ships a bundled agent skill plus a /cbm status command.

---

Features

• Six knowledge-graph code tools registered natively on the DSH tool surface (cbm_projects, cbm_search, cbm_snippet, cbm_arch, cbm_trace, cbm_search_code). The bundled skill's guidance notes that graph queries return precise structural results in ~500 tokens vs ~80K for grep.
• Auto-started background daemon & Web UI — spawns codebase-memory-mcp --ui=true as a child process over stdio JSON-RPC 2.0 (MCP handshake 2025-03-26) when the plugin loads, and prints codebase-memory UI is live: http://localhost:9749/. The shared client restarts the daemon automatically if it exits and disposes it when the plugin shuts down.
• System-prompt guidance — injects a Codebase Memory — Knowledge Graph Policy section that tells the model when to prefer the graph tools over grep/read.
• Bundled agent skill — skills/codebase-memory/SKILL.md is registered as a native bundled skill provider (codebase-memory, rank 600, model- and user-invocable), so the model-facing skill tool can load it.
• /cbm slash command — reports the resolved executable path, the Web UI link, and the projects currently indexed in the daemon.
• Graceful degradation — only tools is a hard dependency (inject: ['tools']); systemPrompt, skills, and commands are attached via deferred ctx.inject(), so a missing host service simply skips that feature.
• Cross-platform executable detection — CBM_EXE override, user and system directories, current working directory, PATH, and a WSL interop fallback that locates codebase-memory-mcp.exe reachable from Linux/WSL.

---

Requirements

Component	Version
DeepSeek Harness	>=0.1.2-rc.1 <0.3.0-0 (dsh.compatibility.dshVersions)
Node.js	>=18 <25 (engines)
codebase-memory-mcp executable	any recent release (tested with 0.11.0)

Optional peer dependencies (declared in peerDependencies, resolved from the DSH runtime when present): @deepseek-ai/cordis >=4.0.1-rc.1 <5.0.0-0, and @deepseek-ai/dsh-commands, @deepseek-ai/dsh-skill, @deepseek-ai/dsh-system-prompt, @deepseek-ai/dsh-tools >=0.1.2-rc.1 <0.3.0-0.

Install the executable before booting DSH. The plugin resolves the binary when it loads; if none is found, the daemon is not started and the cbm_* tools are not registered. Installing the binary later requires reloading the profile.

---

Installation

1. Install the codebase-memory-mcp executable

The plugin is only a bridge — code indexing and querying are done by the codebase-memory-mcp runtime (upstream project, documentation):

# Installs the CLI and downloads/caches the native runtime for your platform
npm install -g codebase-memory-mcp

# Verify it runs
codebase-memory-mcp --version

Alternatively, download your platform's release binary and place it in one of the locations the plugin searches:

• ~/.local/bin/codebase-memory-mcp (Linux/macOS user bin)
• /usr/local/bin/ or /usr/bin/ (system directories)
• the current working directory, or anywhere on PATH
• %USERPROFILE%\AppData\Local\Programs\codebase-memory-mcp\codebase-memory-mcp.exe (Windows)

Or point the plugin at it explicitly with CBM_EXE=/path/to/codebase-memory-mcp.

2. Install the plugin into a DSH profile

dsh plugin --profile web add @lovedolove/dsh-codebase-memory-mcp

(replace web with your profile name — web, headless, sdk, acp, …)

This forwards the package install into the profile directory. Because the package declares dsh.bundle.patch, DSH automatically activates the bundle by appending @lovedolove/dsh-codebase-memory-mcp to the profile's dsh.profile.bundles list.

Other ways to install:

• Web sidebar → Plugins page: search for the package and install it there (the plugin_manager tool exposes the same operations in Creator mode).

• Manual wiring: add the package to the profile's dependencies in $DSH_HOME/profiles/<name>/package.json and list it under dsh.profile.bundles, then run a package install in that directory. The shipped bundle patch (cordis.patch.yml, declared as dsh.bundle.patch) then mounts the plugin:

  - insert:
      - id: codebase-memory
        name: '@lovedolove/dsh-codebase-memory-mcp'
  

3. Start DSH

On plugin load you will see:

[codebase-memory] 🔍 codebase-memory UI is live: http://localhost:9749/

and, in the log:

[codebase-memory] registered tools: cbm_projects, cbm_search, cbm_snippet, cbm_arch, cbm_trace, cbm_search_code
[codebase-memory] registered system prompt guidance
[codebase-memory] registered /cbm command
[codebase-memory] registered skill: codebase-memory

---

Usage

Let the agent use it

The plugin injects the knowledge-graph policy into the system prompt and bundles the codebase-memory skill, so the agent picks the right tool on its own. Typical workflow:

1. cbm_projects() — confirm the project is indexed (by default the project is inferred from the workspace).
2. cbm_search(name_pattern=".*auth.*") — find symbols by name/label/path.
3. cbm_trace(symbol="login", direction="both", max_depth=3) — trace callers and callees.
4. cbm_snippet(qualified_name="app.auth.login") — read the exact definition without loading whole files.
5. cbm_arch(directory="src") — get a directory-level component overview.

Quick decision matrix (from the bundled skill):

Question	Tool call
Who calls X?	cbm_trace(symbol="...", direction="inbound")
What does X call?	cbm_trace(symbol="...", direction="outbound")
Full call context	cbm_trace(symbol="...", direction="both")
Find by name pattern	cbm_search(name_pattern="...")
Read source snippet	cbm_snippet(qualified_name="...")
Directory architecture	cbm_arch(directory="...")
Text search in repo	cbm_search_code(query="...")
List indexed projects	cbm_projects()

Check status with /cbm

🔍 **Codebase Memory MCP**
• Executable: `/home/you/.local/bin/codebase-memory-mcp`
• Web UI: http://localhost:9749/

**Indexed Projects:**
```
home-you-my-repo
```

If the binary is missing, /cbm reports: ⚠️ codebase-memory-mcp executable not found. Install codebase-memory-mcp or set CBM_EXE.

Web UI

The daemon is launched with --ui=true, so an HTTP graph-visualization UI is served at http://localhost:9749/ (the runtime's default port; the upstream binary accepts --port=N and persists it — the plugin's prompts and /cbm assume the default 9749).

---

Available Tools

All six tools accept project (explicit project slug) and/or repo (repository root path, slugified automatically) and are marked concurrency-safe. Results are returned as text.

Tool	Description	Arguments (★ = required)
cbm_projects	List all projects indexed in the daemon	(none)
cbm_search	Search the knowledge graph for symbols or files	name_pattern, label (Function | Class | Interface | File), file_path_pattern, limit (default 50), project, repo
cbm_snippet	Fetch the exact source snippet of a symbol	qualified_name, file_path, start_line, end_line, project, repo
cbm_arch	Architectural summary of a directory (components, entry points, dependencies)	directory (relative to repo root), depth (default 2), project, repo
cbm_trace	Trace inbound/outbound call paths through the graph	★ symbol, direction (inbound | outbound | both, default both), max_depth (default 3), project, repo
cbm_search_code	Fast textual regex search over indexed files	★ query, file_pattern, limit (default 50), project, repo

Each tool forwards to the daemon's MCP tools/call method (list_projects, search_graph, get_code_snippet, get_architecture, trace_path, search_code) with a 120-second timeout; tool-level errors are surfaced as failed tool results.

---

Configuration

Environment variables

Variable	Effect
CBM_EXE	Explicit path to the codebase-memory-mcp binary (must exist; takes priority over every other lookup).
CBM_DEFAULT_PROJECT	Fallback project slug when neither project nor repo is passed to a tool.

Project resolution order

When a tool is called, the project is resolved as:

1. explicit project argument,
2. slug of the repo argument,
3. CBM_DEFAULT_PROJECT,
4. slug of the current working directory.

Slug mapping: /home/user/my-repo → home-user-my-repo; Windows paths keep a drive prefix, e.g. C:\Users\me\app → C-Users-me-app.

Daemon auto-start

The daemon starts eagerly when the plugin applies (unless the process runs under node --test), and every tool call ensures it is running, so the child process is restarted transparently if it dies. On plugin disposal the daemon is killed together with any pending requests.

---

Development & Testing

# Unit + integration test suite (node --test)
npm test

# Verify npm package packing
npm run pack:check

The suite covers path slugification, findExe/CBM_EXE lookup, the stdio JSON-RPC client (spawn, handshake, tool calls, errors), tool registration, a full apply() against a mocked Cordis context, and — when the real binary is installed on the host — a live list_projects round trip (this test is skipped otherwise). CI runs the suite on Ubuntu with Node 20, 22, and 24.

Repository layout:

src/index.mjs        # Cordis plugin: apply(), system prompt, /cbm command
src/bridge.mjs       # stdio JSON-RPC client, executable discovery, cbm_* tools
src/skills.mjs       # bundled skill provider registration
skills/codebase-memory/SKILL.md   # agent-facing skill
cordis.patch.yml     # bundle patch that mounts the plugin

Publishing

Every push to main runs the Publish workflow: it runs the test suite and publishes the package to npm via Trusted Publishing (OIDC). If the current version already exists, the workflow bumps the patch version and commits it back with [skip publish] to avoid a loop; including [skip publish] anywhere in a commit message skips the publish run entirely.

---

License

MIT © 2025 LoveDoLove