dsh-tool-codebase-memory

[!NOTE]

📦 This plugin lives in the dsh-plugins monorepo — file issues & pull requests there.

npm: @hy-sde-org/dsh-tool-codebase-memory

dsh-tool-codebase-memory — codebase-memory CLI tools for DeepSeek Harness

A standalone package, installable as one plugin (fourteen tools) for the DeepSeek Harness CLI:

package · tools · installed by users? @hy-sde-org/dsh-tool-codebase-memory · codebase_list_projects, codebase_index_repository, codebase_index_status, codebase_search_graph, codebase_query_graph, codebase_trace_path, codebase_get_code_snippet, codebase_get_graph_schema, codebase_get_architecture, codebase_search_code, codebase_detect_changes, codebase_manage_adr, codebase_ingest_traces, codebase_delete_project · yes

This is the DeepSeek Harness packages/codebase-memory/tool-codebase-memory package — the model-facing codebase_* tools wrapped over the codebase-memory-mcp CLI — ported to the hy-sde npm scope as a standalone plugin with zero upstream harness changes: every @deepseek-ai dependency resolves from the npm registry at the 0.2.0-rc.2 baseline, so it installs on official DeepSeek Harness releases (dsh-v0.2.0-rc.2 and later) exactly as it runs in the fork. The CLI is not bundled: install codebase-memory-mcp (or point cliPath at a non-PATH binary) and the plugin runs against the same local daemon the stdio MCP client fronts.

Summary

The package exposes the local codebase-memory daemon as model-facing codebase_* tools that run one-shot queries from the terminal. Each call spawns codebase-memory-mcp cli --json once with a temp --args-file and parses the raw MCP result envelope — indexes, project mutation locks and the index supervisor are shared with the MCP server's daemon, and no long-lived server lives inside the session. See the package README for the full tool surface, configuration, and the CLI-vs-MCP rationale.

Why

Structural code questions — definitions, callers, call chains, routes, cross-service links, architecture — are graph questions, and answering them with ad-hoc grep/read cycles costs repeated scans and still misses hops. The codebase-memory knowledge graph answers them in one call instead: codebase_search_graph for definitions, implementations, and relationships; codebase_trace_path for callers/callees and cross-service routes; codebase_get_architecture for the de-facto module map; and codebase_query_graph for multi-hop Cypher the curated tools cannot express.

Unlike an in-session MCP server, each tool is a one-shot terminal spawn — codebase-memory-mcp cli --json once with a temp --args-file, parsing the raw MCP result envelope — against the same local daemon the stdio MCP client fronts: indexes, project mutation locks, and the index supervisor are shared with that daemon, and no long-lived server lives inside the session.

Table of Contents

• Why
• Prerequisites
• Install
• Run
• Mounting
• License

Prerequisites

• Node.js 22.19 or newer (the package's engines floor) with npm and pnpm on PATH;
• a DeepSeek Harness installation including the standard dsh CLI — the package's peer

baseline is @deepseek-ai/cordis ~4.0.4 and @deepseek-ai/dsh-tools/@deepseek-ai/dsh-system-prompt ^0.2.0-rc.2;

• the external codebase-memory-mcp

CLI — not bundled. Install it (or point the row's cliPath config at a non-PATH binary); the plugin runs against the same local daemon the stdio MCP client fronts.

Install

pnpm install --global @deepseek-ai/dsh

Direct from npm (published)

dsh plugin --profile web add @hy-sde-org/dsh-tool-codebase-memory

dsh plugin add reconciles the profile's bundle list from the installed dsh.bundle.patch export, so after installation the hy-sde-cbm-tool-codebase-memory row below is immediately active in the named profile.

You can also just depend on the package from your own tooling:

npm install @hy-sde-org/dsh-tool-codebase-memory   # or pnpm add / yarn add

From this repository (pre-publish / development)

git clone git@github.com:hy-sde/dsh-plugins.git
cd dsh-plugins
pnpm install
pnpm --filter @hy-sde-org/dsh-tool-codebase-memory build

CBM_TGZ="$(cd dsh-tool-codebase-memory/packages/tool-codebase-memory && pnpm pack --pack-destination /tmp | tail -n 1)"
dsh plugin --profile web add "$CBM_TGZ"

prepack rebuilds dist/, so the tarball is always current.

Verify

dsh web --dump-config   # look for the hy-sde-cbm-tool-codebase-memory row

Run

Ask the agent structural questions — each codebase_* call is one terminal spawn:

• codebase_search_graph with a natural-language query (e.g. "where is the profile

patch loader implemented") — definitions, implementations, and relationships ranked by structural importance; page with limit/offset until has_more is false.

• codebase_query_graph with a raw cypher query — multi-hop patterns, aggregations,

and cross-service analysis the curated tools cannot express.

Uninstall

dsh plugin --profile web remove @hy-sde-org/dsh-tool-codebase-memory

Already shipped? If a future DeepSeek Harness release ships

codebase-memory tooling itself, skip installation — adding this bundle on

top would duplicate the loader row and fail at boot.

Mounting

The plugin's cordis.patch.yml mounts one plain agent-plane row, exactly like the official harness's own tool-codebase-memory row in the stock base bundle. It consumes the deployment's host services — tools and systemPrompt (stock base provides both via the agent bundle) — so it needs no service or filesystem realm of its own:

• hy-sde-cbm-tool-codebase-memory — @hy-sde-org/dsh-tool-codebase-memory,

registering the fourteen codebase_* tools and the codebase:tools prompt section.

Configure per deployment by patching the row by id:

- id: hy-sde-cbm-tool-codebase-memory
  config:
    cliPath: /opt/codebase-memory-mcp/bin/codebase-memory-mcp
    project: my-monorepo
    timeoutMs: 60000
    indexTimeoutMs: 600000
    maxChars: 200000

The row id carries the hy-sde- prefix to avoid clashing with any shipped row of the same name (a duplicate loader id fails the boot); if the deployment already mounts a tool-codebase-memory row of its own, disable this one or drop the insert and keep the stock row.

License

MIT — see LICENSE. Derived from the DeepSeek Harness tool-codebase-memory package (@deepseek-ai/dsh-tool-codebase-memory, MIT) — see THIRD-PARTY-NOTICES.md.