DevBrain

Persistent developer memory for you and your AI agents. Captures knowledge from git commits, lets you save typed notes instantly, surfaces relevant past solutions by meaning — and injects that context directly into Claude before it starts coding.

---

What it does

• Auto-captures knowledge from every git commit — Gemini extracts the problem, solution, and tags automatically
• Semantic search across all projects — finds past solutions by meaning, not keyword
• Instant typed saves — bug:, fix:, decision:, pattern:, lesson:, stack: prefixes save without any AI call
• Context injection — devbrain context builds a ranked, compressed snapshot of your engineering memory for AI agents to reason from before starting a task
• MCP server — Claude Code calls get_context, search_knowledge, and save_entry automatically during sessions
• Browse all saved entries with arrow-key navigation
• Export everything to a .zip with organized .txt files per type
• Cross-project — search and context span every registered project

---

Install

git clone https://github.com/pushthev1be/devbrain.git
cd devbrain
npm install --ignore-scripts
npm run build --workspace=packages/core
npm run build --workspace=packages/cli

# Link globally
cd packages/cli
npm link

First run walks you through a 3-step setup wizard: API key, project registration, and git hook.

Gemini API key

Get a free key at aistudio.google.com. The wizard will prompt you for it, or set it manually:

mkdir -p ~/.devbrain
echo "GEMINI_API_KEY=your_key_here" > ~/.devbrain/.env

Claude Code (MCP) integration

Build the MCP package and register it once:

npm run build --workspace=packages/mcp

claude mcp add devbrain node "/absolute/path/to/devbrain/packages/mcp/dist/index.js"

Claude now has four tools available every session:

Tool	When Claude calls it
get_context	At the start of any non-trivial task — injects ranked historical context
search_knowledge	When searching for a past solution to a specific problem
save_entry	After fixing a bug or making an architectural decision
get_project_summary	To understand what's already captured for a project

---

Interactive REPL

devbrain

Two separator lines mark the input area. Type freely to search. Type / to open the command picker:

────────────────────────────────────────────────────────────────────────────────
devbrain  ❯ /
────────────────────────────────────────────────────────────────────────────────
❯ /search       Semantic search across all projects
  /context      Inject ranked context for AI agents
  /browse       Scroll through all saved entries
  /save         Save entry  (bug: fix: stack: decision: pattern: lesson:)
  /summary      Project name, stack and recent entries
  /export       Export knowledge to zip file
  /init         Register project + install git hook
  /clear        Clear the screen
  /exit         Quit DevBrain

---

Quick saves

Type a prefix directly at the prompt — saved instantly, no AI call:

bug: JWT token expires in production but not locally
fix: set TOKEN_EXPIRY=86400 in the prod .env
stack: React, TypeScript, Vite, TailwindCSS, Node
decision: use JSON file storage — avoids native compilation on Windows
pattern: always run npm install --ignore-scripts on Windows
lesson: run migrations before deploying

Prefix	Type	Color
bug:	bug	red
fix:	fix	green
stack:	stack	cyan
decision:	decision	magenta
pattern:	pattern	yellow
lesson:	lesson	yellow
solution:	solution	green
(no prefix)	note	blue

---

Context injection

devbrain context              # general project context
devbrain context "auth"       # focused on a topic

Outputs a ranked, deduplicated snapshot grouped into:

# DevBrain Context — TuneCity — "auth"

## Past Issues & Fixes
• Auth failures are commonly caused by environment token mismatch
• Refresh token race conditions resolved by serializing requests
• Container timezone drift affects JWT expiry validation

## Architecture Decisions
- Stateless JWT preferred over Redis sessions for the MVP

## Patterns & Lessons
- Always verify TOKEN_EXPIRY is consistent across Docker containers

## Tech Stack
React · TypeScript · Node.js · Express · MongoDB

Sections with 2+ entries are synthesized by Gemini into bullet-point insights — token-efficient and agent-readable. The MCP get_context tool returns this format automatically.

Ranking formula: semantic × 0.55 + recency × 0.15 + same-project × 0.15 + same-stack × 0.10 The same-project boost only applies when the entry is already semantically relevant (score > 0.72), preventing local noise from outranking better cross-project solutions.

---

Auto-capture from git

After devbrain init, a post-commit hook runs after every commit. Gemini extracts:

• The problem being solved
• The solution applied
• Relevant tags (language, framework, error type)
• Entry type (bug / fix / note)

If Gemini is rate-limited, the commit is left unprocessed and retried next time — no knowledge is lost.

---

Non-interactive CLI

devbrain init              # register project + install git hook
devbrain search "query"    # semantic search
devbrain context "topic"   # ranked context snapshot
devbrain note "bug: ..."   # save a note
devbrain summary           # project info
devbrain export            # export to zip
devbrain capture           # manually process last git commit

---

Export

devbrain export

Creates ~/.devbrain/<project>-export.zip containing one .txt file per entry type, each listing date, title, details, and tags.

---

Storage

Everything is local. Nothing is sent anywhere except the Gemini API for AI features.

~/.devbrain/
  db.json          # all projects, entries, and processed commits
  .env             # GEMINI_API_KEY
  setup.json       # first-run onboarding state
  *-export.zip     # exports

---

Stack

• Runtime: Node.js
• Language: TypeScript
• AI: Gemini 2.0 Flash (generation + synthesis) · gemini-embedding-001 (semantic search)
• Storage: Pure JSON — no native dependencies, works on all platforms
• CLI: inquirer · inquirer-autocomplete-prompt
• MCP: @modelcontextprotocol/sdk
• Monorepo: npm workspaces (packages/core · packages/cli · packages/mcp)