<div align="center">

# ⚡ ContextWeave

### Universal Project Memory Engine

**Stop losing context. Start building faster.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/badge/npm-v0.1.0-blue)](https://npmjs.com/package/contextweave)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)
[![GitHub Stars](https://img.shields.io/github/stars/deyavinaba597-pixel/contextweave?style=social)](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

```bash
# 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.

```bash
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`](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`):

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

---

## Architecture

See [`docs/ARCHITECTURE.md`](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`](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](LICENSE)

---

<div align="center">

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

**[Documentation](docs/)** • **[Examples](examples/)** • **[Contributing](docs/CONTRIBUTING.md)** • **[GitHub](https://github.com/deyavinaba597-pixel/contextweave)**

</div>