⚡ ContextWeave

Universal Project Memory Engine

Stop losing context. Start building faster.

![License: MIT](https://opensource.org/licenses/MIT) ![npm version](https://npmjs.com/package/contextweave) ![Node.js](https://nodejs.org) ![MCP Compatible](https://modelcontextprotocol.io) ![GitHub Stars](https://github.com/deyavinaba597-pixel/contextweave)

Works with Cursor • Claude Desktop • Kiro • GitHub Copilot • any MCP-compatible AI

</div>

---

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 ```typescript // 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 ```bash 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: ``json { "mcpServers": { "contextweave": { "command": "contextweave", "args": ["mcp"] } } } ``

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json: ``json { "mcpServers": { "contextweave": { "command": "contextweave", "args": ["mcp"] } } } ``

Kiro

Add to .kiro/settings/mcp.json: ``json { "mcpServers": { "contextweave": { "command": "contextweave", "args": ["mcp"] } } } ``

VS Code + GitHub Copilot

Add to .vscode/settings.json: ``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

[x] 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

---

Built with ❤️ for developers who write // WHY: comments

Documentation • Examples • Contributing • GitHub