---

The Problem

Every developer knows this moment:

"Why is this function written this way?"
"Why did we choose PostgreSQL over MongoDB?"
"Why is there a 500ms sleep in this critical path?"

You dig through git blame, search Slack, ping colleagues who may have left. The context is gone. You either make a decision blind, or spend hours reconstructing what someone already figured out.

This is the #1 productivity killer in software development. Context loss costs teams hours every week — and it compounds. AI coding assistants make it worse: they have no memory of your project's history, constraints, or the reasoning behind past decisions.

---

The Solution

ContextWeave is a local-first, zero-config project memory engine that automatically:

• 🔍 Watches your codebase and extracts a living knowledge graph — every file, function, class, and module
• 📜 Mines your git history for architectural decisions buried in commit messages
• 💬 Extracts WHY comments (// WHY:, // DECISION:, // NOTE:) from your source code
• 🗄️ Stores everything in SQLite locally — your data never leaves your machine
• 🤖 Serves an MCP server so ANY AI coding assistant can query full project context instantly
• 🖥️ Provides a CLI for humans to explore, search, and annotate the knowledge graph
• 🌐 Includes a web dashboard to visualize everything — no build step required

                    Your Codebase
                         │
          ┌──────────────┼──────────────┐
          │              │              │
       git log      source files   package.json
          │              │              │
          └──────────────┼──────────────┘
                         │
                   ContextWeave
                    (watching)
                         │
                  SQLite Database
                  (local, yours)
                         │
           ┌─────────────┼─────────────┐
           │             │             │
         CLI           MCP          Dashboard
      (humans)      (AI tools)     (browser)

---

Quick Start

# Install globally
npm install -g contextweave

# Initialize in your project
cd my-project
contextweave init

# Scan — builds the knowledge graph (~5s for most projects)
contextweave scan

# Start the MCP server for your AI assistant
contextweave mcp

Tip: cw is a built-in short alias — cw scan, cw why src/auth.ts, etc.

That's it. Your AI assistant now has full project context.

---

Features

🏛️ Decision Capture — The "Why" Layer

ContextWeave extracts architectural decisions from three sources:

1. Git history mining

commit 7f3a9b2
Author: Sarah Chen

Switched auth from JWT to session-based

Performance benchmarks showed JWT verification was adding 12ms latency
per request. With 500+ concurrent users, sessions with Redis reduces
this to <1ms for cached sessions.

→ Captured as a decision: "Switched from JWT to session-based auth"

2. WHY/DECISION comments

// WHY: We use exponential backoff here instead of fixed delays because
//      thundering herd problems killed us in production with 500+ clients.
async function retryWithBackoff(fn: () => Promise<void>) {

// DECISION: Chose PostgreSQL over MongoDB for ACID transaction support
//           needed by the payment flow. Benchmarked both — Mongo was 15%
//           faster for reads but we can't sacrifice consistency.
const db = createConnection(DATABASE_URL);

3. Manual recording

contextweave decide
# Interactive prompts to record any decision

🤖 MCP Server — AI Superpowers

Once connected to your AI assistant, it gains 8 powerful tools:

Tool	What it does
search_context	Semantic search over all knowledge
get_file_context	Full history + symbols for any file
get_decisions	All architectural decisions with rationale
add_decision	Record a decision mid-conversation
get_project_summary	Languages, frameworks, stats
find_related	Code related to any term
get_recent_changes	Recent commits with context
annotate	Add notes to any file or function

Example: Ask your AI "Before refactoring auth, check what decisions were made" — it'll call get_file_context and surface the JWT→sessions migration rationale automatically.

⚡ CLI — Human-Friendly

Both contextweave and cw work as the command name.

cw search "rate limiting"            # Find anything in the knowledge base
cw why src/api/middleware.ts         # Understand a file — symbols, decisions, notes
cw decisions --source git            # All decisions extracted from git history
cw annotate src/auth.ts "Uses PKCE"  # Add a note to a file
cw decide                            # Interactively record an architectural decision
cw export --format markdown          # Export full knowledge as Markdown ADR doc
cw status                            # Project health at a glance
cw watch                             # Live updates as you code
cw dashboard                         # Open visual web dashboard
cw mcp                               # Start MCP server for AI tools

🌐 Dashboard

A beautiful, zero-dependency web UI (single HTML file, no build step):

• Real-time stats: nodes indexed, decisions captured, last scan
• Searchable decision log with source attribution (GIT/COMMENT/MANUAL)
• File explorer with full context
• Recent git activity feed
• One-click decision recording

---

Language Support

Language	Files	Functions	Classes	Comments
TypeScript	✅	✅	✅	✅
JavaScript	✅	✅	✅	✅
Python	✅	✅	✅	✅
Go	✅	✅	✅ (structs)	✅
Rust	✅	✅	✅ (structs)	✅
Java	✅	—	—	✅
Ruby	✅	—	—	✅

Dependency manifests: package.json, requirements.txt, go.mod, Cargo.toml

---

MCP Setup

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "contextweave": {
      "command": "contextweave",
      "args": ["mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "contextweave": {
      "command": "contextweave",
      "args": ["mcp"]
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "contextweave": {
      "command": "contextweave",
      "args": ["mcp"]
    }
  }
}

VS Code + GitHub Copilot

Add to .vscode/settings.json:

{
  "github.copilot.chat.mcp.enabled": true,
  "mcp": {
    "servers": {
      "contextweave": {
        "type": "stdio",
        "command": "contextweave",
        "args": ["mcp"]
      }
    }
  }
}

See examples/mcp-config.json for more.

---

Comment Tags Reference

Add these to any source file — ContextWeave extracts them automatically:

// WHY: <rationale>       → Captured as a Decision
// DECISION: <rationale>  → Captured as a Decision
// TODO: <task>           → Captured as an Annotation
// FIXME: <issue>         → Captured as an Annotation  
// NOTE: <info>           → Captured as an Annotation
// HACK: <explanation>    → Captured as an Annotation
// WARN: <warning>        → Captured as an Annotation

Works with // (JS/TS/Go/Rust), # (Python/Ruby). The comment delimiter must be at the start of the (trimmed) line — inline code strings are ignored.

---

All CLI Commands

Command	Description
cw init	Initialize in current directory
cw scan	Full project scan
cw watch	Continuous watch mode
cw search <query>	Search the knowledge base
cw why <file>	Show context for a specific file
cw decisions	List all captured decisions
cw decide	Interactively record a decision
cw annotate <file> <note>	Add a note to a file
cw export	Export knowledge as Markdown or JSON
cw dashboard	Open web dashboard
cw mcp	Start MCP server for AI tools
cw status	Project health stats

---

Configuration

.contextweave/config.json (created by contextweave init):

{
  "projectRoot": "/path/to/project",
  "dbPath": ".contextweave/context.db",
  "watchDebounce": 500,
  "maxFileSizeKb": 500,
  "gitDepth": 300,
  "dashboardPort": 4242,
  "excludePatterns": ["**/generated/**"]
}

---

Architecture

See docs/ARCHITECTURE.md for the full deep-dive.

Stack:

• Storage: SQLite via better-sqlite3 + FTS5 for full-text search
• Watching: chokidar with 500ms debounce
• Parsing: Pure regex (no native deps, runs anywhere)
• MCP: @modelcontextprotocol/sdk over stdio
• CLI: commander + chalk + ora
• Dashboard: Single HTML file, vanilla JS, no build step

---

Roadmap

• v0.1 — Core engine: scan, watch, MCP server, CLI, dashboard
• v0.2 — VS Code extension with inline decision annotations
• v0.3 — Semantic search via local embeddings (ollama/nomic)
• v0.4 — GitHub Actions integration — surface context in PR comments
• v0.5 — Conflict detection — warn when changes contradict past decisions
• v1.0 — Team sync via git notes (zero extra infra)
• Ruby, PHP, Swift, Kotlin language support
• Tree-sitter integration for precise multi-language parsing
• Support for .contextweave/decisions.md manual ADR format
• Automatic documentation generation from knowledge graph

---

Contributing

We'd love your help! See docs/CONTRIBUTING.md.

Good first issues:

• Adding language support (Ruby, PHP, Swift, Kotlin)
• Adding comment patterns for more tag types
• Improving git decision extraction heuristics
• Writing tests

---

Why Local-First?

• Privacy: Your code and decisions never leave your machine
• Speed: SQLite is faster than any cloud API for local queries
• Reliability: Works offline, no rate limits, no authentication
• Portability: The .contextweave/ directory goes with your project

---

License

MIT — see LICENSE

---