The Problem

Claude Code has no persistent memory between sessions. Each conversation starts fresh, forcing users to repeat context, re-explain decisions, and waste cycles rediscovering what was already resolved. With 200K context windows and zero cross-session memory, the model behaves like a goldfish with a PhD — expensive capability squandered on constant reorientation.

What This Does

claude-brain gives Claude photographic memory in a single .mv2 file — no database, no SQLite, no ChromaDB. The repository is built as a GitHub plugin (.claude-plugin/) that integrates with Claude Code, capturing session context, decisions, and bugs auto-injected at session start. The core runtime is native Rust; the observable surface is TypeScript. Entry points are src/index.ts (source) and dist/index.js (compiled). The module graph has 19 internal modules with 21 import edges and zero circular dependencies. The most connected module is src/core/mind (Ca 4, Ce 3, instability 0.43), which owns the memory engine. Supporting hubs are src/types (Ca 5, Ce 0) and src/utils/helpers (Ca 6, Ce 0), both instability‑free. Hooks — post-tool-use, session-start, and stop — each have instability 1, meaning they are pure entry/exit points with no downstream dependencies beyond the core.

How It Is Wired

Execution starts at src/index.ts, which imports and exposes the public API. The hook chain flows through src/hooks/session-start.ts (Ca 0, Ce 2) to prime memory at session open, then src/hooks/post-tool-use.ts (Ca 0, Ce 4, instability 1) captures intent after each tool invocation, and finally src/hooks/stop.ts (Ca 0, Ce 3) on exit. Scripts — ask.ts, find.ts, stats.ts, and timeline.ts — are the consumer-facing commands; each has duplicated 6‑line blocks across the four files (25 repeated blocks total), violating DRY and raising maintainability risk. The src/scripts/utils.ts helper (Ca 4, Ce 0) is the natural extraction target. Search and ask logic funnels through src/core/mind.ts, the single-file memory engine written in Rust (compiled to WebAssembly or linked via neon/FFI). Types live in src/types.ts (Ca 5, Ce 0), a zero‑dependency contract layer. The only high‑instability module beyond the core is src/hooks/post-tool-use.ts, which has 72 branch points over 209 lines — high cognitive load that should be decomposed via strategy dispatch rather than nested if/else.

Outside the repository: the .mv2 file lives at .claude/mind.mv2 per the README; it is a portable binary that can be git‑committed, scp‑ed, or shared. No database, no cloud, no API keys. The plugin metadata lives in .claude-plugin/marketplace.json and .claude-plugin/plugin.json.

How To Use It

Setup — Install the GitHub plugin once (global git config adjustment required per the README), then in Claude Code:

/plugin add marketplace memvid/claude-brain

Enable the mind plugin, restart Claude Code. The .mv2 file will be created at .claude/mind.mv2 on first session.

Running it — No build step is needed for the end user. The dist/ directory contains the compiled bundle; developers build with pnpm build (configured in tsup.config.ts/package.json). For CLI access outside Claude Code, memvid-cli can be installed globally (npm install -g memvid-cli) and invoked as:

memvid stats .claude/mind.mv2
memvid find .claude/mind.mv2 "auth"
memvid ask .claude/mind.mv2 "why JWT?"
memvid timeline .claude/mind.mv2

Configuration is implicit — the .mv2 file is the only artifact. Environment variables or keys are not required.

Real-World Use

A team onboards a new engineer. Instead of copying pastebins of previous sprint notes, the engineer types /mind search "authentication" in Claude Code. The .mv2 file is auto‑injected, and Claude surfaces the exact JWT‑vs‑session decision, the PR link, and the mitigation that was applied three weeks ago. The team later commits .claude/mind.mv2 alongside the code — version‑controlled memory that persists across git clones and scp transfers.

Code Health & Issues

The static analysis (MEASURED ANALYSIS block) found three categories of findings:

  • [HIGH/clarity] Duplicated code blocks across src/scripts/ask.ts, src/scripts/find.ts, src/scripts/timeline.ts, src/scripts/stats.ts — 25 repeated 6‑line blocks. Extract shared helpers into src/utils/helpers.ts.
  • [MEDIUM/cognitive_load] High branching density in src/hooks/post-tool-use.ts and src/scripts/find.ts — 72 branch points over 209 lines. Decompose decision logic into a dispatch table or strategy pattern.
  • [LOW/clarity] 4 TODO/FIXME markers in src/core/mind.ts and src/utils/compression.ts — stale markers that should be triaged or resolved.

SDLC observations from the hygiene audit (8 findings, 0 critical):

  • Pin third‑party GitHub Actions to commit SHAs — .github/workflows/release.yml uses softprops/action-gh-release@v1; tags can move, so pin to the 40‑char SHA.
  • Declare least‑privilege permissions for GITHUB_TOKEN — .github/workflows/ci.yml has no permissions declaration; add contents: read at the top.
  • Enable Dependabot or Renovate — no update bot is configured; commit .github/dependabot.yml for repo ecosystems and github-actions.
  • Gate pull requests on dependency vulnerability scan — no dependency scan in CI; add dependency-review-action on pull_request.
  • Move large binaries to Git LFS or out — tweet_cap.mp4 (35.5MB) and video.mp4 (10.8MB) are committed bloating every clone; track with LFS or fetch in a setup step.
  • Remove generated build output from version control — dist/ has 20 generated files committed; gitignore the output directory and build in CI.
  • Set persist-credentials: false on checkout — ci.yml keeps the token; add with: persist-credentials: false and pass explicit tokens only to pushing steps.
  • Set timeout-minutes on workflow jobs — two workflows have no job timeout; add realistic bounds.

The Bottom Line

This repo solves a genuine pain point — zero‑effort persistent memory for Claude Code via a single portable file. The Rust core is impressive, and the plugin model integrates cleanly with Claude's existing tooling. However, the codebase shows its age: duplicated logic, high‑branching hooks, and committed build output + large binaries inflate clone size and CI cost. The hygiene audit reveals actionable CI/security gaps that should be addressed before promoting this to a production team. Use it if you need instant onboarding memory and are willing to maintain the duplicated scripts and CI fixes; otherwise, the duplicated code and unpinmed Actions present real friction for team adoption.