DevMind

Graph-native project memory for AI dev teams

Replace static CLAUDE.md files with a live knowledge graph that learns from every coding session.

---

The Problem

Every AI coding session starts blind. No memory of past decisions, what broke before, or why the code looks the way it does. Context is lost between sessions.

The Solution

DevMind gives your AI agent a persistent memory that grows automatically:

Before work  →  Agent calls get_project_brief()  →  Gets decisions, landmines, patterns
After work   →  Agent calls log_activity()        →  Graph updated, insights returned

Zero manual tagging. The knowledge graph builds itself.

---

Quick Start

1. Install

pip install -r requirements.txt
cp .env.example .env  # add your API keys + SurrealDB credentials

2. Setup

python devmind.py setup   # create database schema
python devmind.py seed    # load demo data (optional)

3. Connect Your Agent

Claude Code — add .mcp.json to your project root

{
  "mcpServers": {
    "devmind": {
      "command": "python",
      "args": ["/path/to/dev-mind/mcp_server.py"]
    }
  }
}

VS Code Copilot — add .vscode/mcp.json

{
  "servers": {
    "devmind": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/dev-mind/mcp_server.py"]
    }
  }
}

4. Verify

python devmind.py brief --project auth-service

---

How It Works

┌─────────────────┐                    ┌─────────────────┐
│  SESSION START   │                    │  TASK COMPLETE   │
│                  │                    │                  │
│  get_project_    │                    │  log_activity()  │
│  brief()         │                    │                  │
└────────┬────────┘                    └────────┬────────┘
         │                                      │
         ▼                                      ▼
┌─────────────────┐              ┌──────────────────────────┐
│   SurrealDB     │              │  LangGraph Pipeline      │
│                 │              │                          │
│  → tech stack   │              │  parse_extract  (LLM)   │
│  → decisions    │              │       ↓                  │
│  → landmines    │              │  cross_reference (DB)   │
│  → patterns     │              │       ↓                  │
│  → recent fixes │              │  analyze        (LLM)   │
│                 │              │       ↓                  │
│  + agent        │              │  write_graph    (DB)    │
│    instructions │              │       ↓                  │
└─────────────────┘              │  respond       (logic)  │
                                 └──────────────────────────┘

---

MCP Tools

Read Tools (7)

Tool	What it does
get_project_brief(project)	Full brief — tech stack, decisions, landmines, patterns, fixes
get_file_context(project, file)	Everything known about a specific file
get_landmines(project)	Files that have broken repeatedly
search_memory(project, query)	Keyword search across all knowledge
get_recent_activity(project, limit?)	Latest events across all types
get_project_context(project)	Auto-detected metadata (tech stack, purpose)
get_full_memory(project, types?, since?)	Complete graph dump with filters

Write Tool (1)

Tool	What it does
log_activity(project, type, summary, details?, files?)	Report changes — triggers enrichment pipeline

Activity types: fix · error · decision · pattern · feature

---

Example Output

===========================================
  DevMind Brief -- auth-service -- 2026-03-07
===========================================

PROJECT CONTEXT
  tech_stack: TypeScript (85% confidence)

ACTIVE DECISIONS (3)
  * Use JWT over sessions -- 2026-03-06
  * All auth errors return 401 with {code, message} -- 2026-03-06
  * JWT refresh token rotation enabled -- 2026-03-06

LANDMINES (2 known issues that broke before)
  * src/auth.ts: TypeError: Cannot decode malformed JWT token
    Broke 3 times. Last fix: Added null check before JWT decode
  * src/middleware.ts: RateLimiter applied before auth check
    Broke 2 times. Last fix: Moved rate limiter after requireAuth

PATTERNS
  * Never expose stack traces in API responses
  * requireAuth middleware must always run before rate limiting

RECENT FIXES (latest 3)
  * Added null check before JWT decode, return 401 on malformed token
  * Moved rate limiter after requireAuth in middleware chain

===========================================
Generated in 42ms -- 0 LLM tokens used
===========================================

---

Knowledge Graph

DevMind stores everything in SurrealDB as a connected graph:

Nodes

Table	Key Fields
error	message, file, keywords, resolved, landmine, count
fix	description, file, keywords, fix_session
decision	summary, reasoning, keywords, active
pattern	description, file, keywords
file	path, project
context	key, value, confidence, source

Edges: fixed_by · in_file · caused_by · applies_to · affects

A file with 2+ error occurrences is automatically flagged as a landmine.

---

Tech Stack

Component	Role
Python 3.12+	Runtime
FastMCP	MCP server (stdio)
LangGraph	Enrichment pipeline
SurrealDB Cloud	Graph database
GPT-4o-mini	Primary LLM (Claude Haiku fallback)
LangSmith	Tracing & observability

Project Structure

mcp_server.py             MCP entry point (8 tools, stdio)
devmind.py                CLI — setup, seed, status, brief
agent/
  graph.py                LangGraph pipeline definition
  nodes.py                5 node functions + DB write logic
  context_extractor.py    Zero-LLM tech stack detection
  state.py                ActivityState TypedDict
db/
  client.py               Async SurrealDB wrapper
  schema.surql            Schema (6 node + 5 edge tables)
brief/
  generator.py            Zero-LLM brief builder
seed/
  seed_data.py            Demo data (auth-service)

Environment Variables

# LLM (at least one required)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# SurrealDB
SURREAL_URL=wss://your-instance.surreal.cloud/rpc
SURREAL_USER=root
SURREAL_PASS=your_password
SURREAL_NS=devmind
SURREAL_DB=devmind

# LangSmith (optional)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_pt_...
LANGCHAIN_ENDPOINT=https://eu.api.smith.langchain.com
LANGCHAIN_PROJECT=devmind

---

MIT License