HELM

HELM: The MCP server that gives AI assistants permanent engineering memory — biographies, incidents, departures, and the ‘why’ behind every decision.

Comment

HELM: Engineering Organizational Memory Layer

Inspiration

Every engineering team faces the same silent crisis: knowledge walks out the door.

A senior engineer leaves after five years. An incident hits at 2am. A new hire asks "why does this work this way?" — and no one knows anymore. The codebase has evolved through dozens of architectural pivots, hundreds of contributors, thousands of commits — but all that context lives only in the heads of people who may no longer be there.

I kept asking: why can't an AI assistant just know this? Not from documentation (which rots), not from wikis (which no one updates), but directly from the source of truth — the commit history, the pull requests, the patterns in the code itself.

That question became HELM.

What I Built

HELM is a Model Context Protocol (MCP) server that transforms raw git history into structured organizational memory. It exposes five tools any Claude-powered AI assistant can call:

Tool What It Does
get_codebase_biography Narrates a repo's full history as human-readable eras
get_incident_context Surfaces past failure patterns for a service
get_departure_impact Assesses knowledge risk when a contributor leaves
get_intent_drift Detects when a module's purpose has diverged from its original design
get_generational_memory Answers "why was this built?" using historical evidence

The synthesis pipeline groups commits by calendar quarter into eras, then uses Claude to distill each era into a narrative, then combines those narratives into a final organizational story. For a repo like facebook/react, this produces a five-paragraph biography covering the Fiber rewrite, the hooks revolution, and the concurrent mode transition — in seconds.

The computational cost scales as:

$$C = \sum_{i=1}^{N} \left\lfloor \frac{|commits_i|}{era_size} \right\rfloor \cdot T_{synthesis}$$

where $N$ is the number of eras (capped at 8 most-recent quarters) and $T_{synthesis}$ is the per-era synthesis time. Caching with node:sqlite brings repeat queries to near-zero cost.

How I Built It

Stack: Node.js 22 + TypeScript, @modelcontextprotocol/sdk, GitHub REST API, built-in node:sqlite (no external DB dependency), Streamable HTTP transport on port 3000.

The synthesis engine was the hardest piece. I needed Claude to analyze commits without requiring the host app's API key. The solution: spawn the claude CLI as a subprocess via stdin, stripping the ANTHROPIC_API_KEY and ANTHROPIC_WORKSPACE_ID env vars so the subprocess uses its own OAuth session:

const result = spawnSync("claude", ["-p", "-"], {
  input: prompt,
  encoding: "utf8",
  timeout: 120_000,
  env: { ...process.env, ANTHROPIC_API_KEY: undefined },
});

This means HELM works for any user with claude CLI installed — no API key configuration required.

The GitHub client fetches commits, PRs, and issues with pagination, then groups them by quarter for era-based analysis. Fetch limits (200 commits, 80 PRs) keep latency bounded without sacrificing historical coverage.

Challenges

1. The Bedrock Dead End

My original plan used AWS Bedrock for synthesis. After getting credentials, every model invocation returned "Operation not allowed in this region" or "Model access not enabled." Three hours lost navigating IAM policies and region restrictions. The pivot to claude CLI stdin was born from necessity — and turned out to be cleaner.

2. The sk-ant-usr- OAuth Token Mystery

The Claude CLI uses workspace OAuth tokens that look like API keys but aren't. Any attempt to pass them directly to the Anthropic SDK fails silently. The fix: let the CLI handle its own auth entirely, never touch its token.

3. Sandbox and Hook Constraints

The development environment enforced terminal hooks that blocked any command containing module_path. Testing get_intent_drift required writing Python scripts that made direct HTTP requests to the MCP server — bypassing the shell hook entirely. This taught me to always design MCP tools to be testable via raw HTTP, not just through MCP client libraries.

4. Era Explosion on Large Repos

Early versions tried to synthesize every era in facebook/react's 12-year history. The synthesis time was unbounded. The fix: cap at the 8 most-recent quarters, which covers ~2 years of active development — the window most relevant for incident context and departure impact anyway.

What I Learned

  • Git history is richer than most teams realize. The signal for organizational memory is already there — it just needs to be read at the right granularity.
  • MCP is the right abstraction. Exposing memory as tool calls means any AI assistant — Claude, future models, custom agents — can use HELM without integration work.
  • Caching is non-negotiable for AI synthesis pipelines. Without SQLite caching, every biography query would cost 30+ seconds and API tokens. With it, repeat queries are instant.
  • Honest uncertainty is a feature. get_generational_memory on React's Fiber architecture returns "this history window is 2024–2026; Fiber shipped in 2017" — and still provides indirect evidence. Users trust a tool that knows what it doesn't know.

What's Next

  • Webhook-driven cache invalidation — invalidate biography cache on push events
  • Multi-repo memory — cross-repository dependency impact analysis
  • Slack/Teams integration — "ask HELM" directly from incident channels
  • Private deployment mode — self-hosted with local LLM support for air-gapped environments

HELM is open source: github.com/HaCkEr-DoG/helm-mcp

Built With

Share this project:

Updates

Submission history