neuronlayer 0.1.7 → 0.1.9

package/README.md

@@ -1,6 +1,8 @@
 # NeuronLayer
 
-**Persistent memory layer for AI coding assistants. Your codebase documents itself.**
+**Persistent codebase understanding for AI assistants.**
+
+NeuronLayer is an MCP server that indexes your codebase and gives AI assistants like Claude the ability to understand your project's structure, dependencies, and history across sessions.
 
 [![npm version](https://img.shields.io/npm/v/neuronlayer.svg)](https://www.npmjs.com/package/neuronlayer)
 [![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
@@ -9,216 +11,152 @@
 
 ---
 
-## The Problem
-
-AI coding assistants are powerful but forgetful:
-
-- Context collapse - AI forgets mid-session
-- No persistent memory - every session starts fresh
-- Code duplication - AI doesn't know what already exists
-- Test breakage - AI suggestions break existing tests
+## What NeuronLayer Does
 
-## The Solution
+- **Indexes your code** - Extracts functions, classes, imports, and exports using regex parsing
+- **Builds a dependency graph** - Tracks what files import what, transitively
+- **Analyzes impact** - Shows which files are affected when you change something
+- **Detects circular dependencies** - Finds import cycles in your codebase
+- **Indexes tests** - Identifies test files and what source files they cover
+- **Records decisions** - Stores architectural decisions that persist across sessions
+- **Semantic search** - Find code by meaning using local embeddings
 
-NeuronLayer gives AI assistants persistent, intelligent memory:
-
-- **Decisions persist** - Architectural decisions survive across sessions
-- **Patterns learned** - AI knows your coding conventions
-- **Context preserved** - Smart compaction prevents forgetting
-- **Tests respected** - AI knows what tests exist
-
----
-
-## Compatibility
-
-| Tool | Supported | Auto-Configure |
-|------|-----------|----------------|
-| Claude Desktop | Yes | `neuronlayer init` |
-| Claude Code (CLI) | Yes | `neuronlayer init` |
-| OpenCode | Yes | `neuronlayer init` |
-| VS Code + Continue | Yes | Manual config |
-| Cursor | Not yet | No MCP support |
-| Any MCP Client | Yes | Manual config |
+All processing happens locally on your machine. No cloud services, no telemetry.
 
 ---
 
 ## Quick Start
 
-### Installation
-
 ```bash
+# Install
 npm install -g neuronlayer
-```
 
-### One-Command Setup
-
-```bash
+# Initialize in your project
 cd your-project
 neuronlayer init
 ```
 
-That's it! This automatically:
-1. Registers your project
-2. Configures Claude Desktop
-3. Configures OpenCode
-4. Configures Claude Code
-
-Just restart your AI tool and NeuronLayer is active.
+This registers your project and configures Claude Desktop, Claude Code, and OpenCode automatically. Restart your AI tool and you're ready.
 
 ---
 
-## MCP Tools
-
-NeuronLayer exposes **14 MCP tools** organized into 6 gateway tools and 8 standalone tools.
-
-### Gateway Tools (Smart Routing)
-
-These are the main tools. Each routes to multiple internal capabilities based on input:
+## Supported AI Tools
 
-| Tool | Purpose |
-|------|---------|
-| `memory_query` | Search codebase, find code, look up symbols, get file context |
-| `memory_record` | Save decisions, learn patterns, record feedback, track features |
-| `memory_review` | Pre-code review: check patterns, conflicts, tests, get suggestions |
-| `memory_status` | Project overview, architecture, recent changes, health check |
-| `memory_ghost` | Proactive intelligence: conflicts, "you solved this before", session resume |
-| `memory_verify` | Pre-commit check: validate imports, security, dependencies |
+| Tool | Setup |
+|------|-------|
+| Claude Desktop | `neuronlayer init` (auto) |
+| Claude Code (CLI) | `neuronlayer init` (auto) |
+| Cursor | `neuronlayer init` (auto) |
+| OpenCode | `neuronlayer init` (auto) |
+| Any MCP Client | Manual config |
+| **Any tool (HTTP)** | `neuronlayer serve` |
 
-### Standalone Tools
-
-| Tool | Purpose |
-|------|---------|
-| `memory_refresh` | **NEW** Trigger manual refresh after external changes (git pull) |
-| `get_refresh_status` | **NEW** Check idle tasks, activity status, git state |
-| `switch_project` | Switch between registered projects |
-| `switch_feature_context` | Resume work on a previous feature |
-| `trigger_compaction` | Reduce memory when context is full |
-| `update_decision_status` | Mark decisions as deprecated/superseded |
-| `export_decisions_to_adr` | Export decisions as ADR markdown files |
-| `discover_projects` | Find git repos on the system |
+All tools share the same data - switch between them freely.
 
 ---
 
-## Features
-
-### What's Implemented
-
-| Feature | Status | Description |
-|---------|--------|-------------|
-| **Semantic Search** | Working | Find code by meaning using embeddings |
-| **Decision Recording** | Working | Log architectural decisions with context |
-| **Pattern Library** | Working | Learn and validate coding patterns |
-| **File Indexing** | Working | AST-based symbol extraction |
-| **Context Compaction** | Working | Smart summarization when context fills |
-| **Test Indexing** | Working | Index tests, predict failures |
-| **Git Integration** | Working | Track changes, correlate with decisions |
-| **Multi-Project** | Working | Switch between projects |
-| **Intelligent Refresh** | **NEW** | Smart sync with cheap pre-checks |
+## What You Can Ask
 
-### Intelligent Refresh System (v0.1.4)
-
-NeuronLayer now includes a tiered refresh architecture that eliminates wasteful polling:
+Once NeuronLayer is running, your AI assistant can:
 
+**Understand dependencies:**
 ```
-TIER 1: REAL-TIME
-├── File changes → Chokidar watcher → immediate invalidation
-├── User queries → immediate tracking
-└── File access → immediate hot cache update
-
-TIER 2: ON-DEMAND WITH CHEAP PRE-CHECK
-├── Git sync → check HEAD first (5ms), only sync if changed
-├── Summaries → check lastModified before regenerating
-└── Bug diagnosis → sync git first if HEAD changed
-
-TIER 3: IDLE-TIME MAINTENANCE
-├── When user idle > 30s AND git changed → sync git
-├── When idle > 5min since last update → update importance scores
-└── One task at a time, non-blocking
-
-TIER 4: SESSION-BASED
-├── Engine init → full git sync
-└── Shutdown → persist state
+"What files depend on src/auth/login.ts?"
+"Show me the import chain for this module"
 ```
 
-**Key optimization**: Instead of running expensive `git log` operations (~100ms+), we cache the HEAD commit and only sync when it changes (~5ms check).
+**Analyze impact:**
+```
+"If I change this file, what else might break?"
+"What tests cover this function?"
+```
 
-### Modules
+**Find code:**
+```
+"Find all authentication-related code"
+"Where is the user validation logic?"
+```
 
+**Check for issues:**
 ```
-src/core/
-├── refresh/             # NEW: Intelligent refresh system
-├── living-docs/         # Architecture & changelog generation
-├── context-rot/         # Context health & compaction
-├── confidence/          # Source tracking & conflict detection
-├── change-intelligence/ # Git tracking & fix suggestions
-├── architecture/        # Pattern library & validation
-└── test-awareness/      # Test indexing & failure prediction
+"Are there any circular dependencies?"
+"What decisions have we made about authentication?"
 ```
 
 ---
 
 ## How It Works
 
-```
-+-------------------------------------------------------------+
-|                      NEURONLAYER                             |
-+-------------------------------------------------------------+
-|                                                              |
-|  +--------------+    +--------------+    +--------------+   |
-|  |   AI Tool    |--->|  MCP Server  |--->|   Memory     |   |
-|  | Claude/Open  |    |   (stdio)    |    |   Engine     |   |
-|  +--------------+    +--------------+    +--------------+   |
-|                                                    |         |
-|                            +--------------------+--+----+   |
-|                            |                    v       |   |
-|  +--------------+    +-----+----+    +------------------+|  |
-|  |  Your Code   |--->| Indexer  |--->|  SQLite + Vec DB ||  |
-|  |  (watched)   |    | (AST/Git)|    |  (embeddings)    ||  |
-|  +--------------+    +----------+    +------------------+|  |
-|                                                          |  |
-+-------------------------------------------------------------+
-```
+NeuronLayer watches your project and maintains:
+
+1. **Symbol index** - Functions, classes, imports, exports
+2. **Dependency graph** - File-to-file import relationships
+3. **Decision log** - Architectural decisions you've recorded
+4. **Embeddings** - For semantic search (using MiniLM-L6 locally)
+
+When your AI assistant asks a question, NeuronLayer provides the relevant context.
+
+---
+
+## Language Support
 
-### Memory Tiers
+| Language | What's Extracted |
+|----------|------------------|
+| TypeScript/JavaScript | Functions, classes, imports, exports |
+| Python | Functions, classes, imports |
+| Go | Functions, structs, imports |
+| Rust | Functions, structs, imports |
+| Java | Classes, methods, imports |
 
-1. **Tier 1** - Hot cache for active files (instant)
-2. **Tier 2** - SQLite for decisions, patterns, history (fast)
-3. **Tier 3** - Vector embeddings for semantic search (smart)
+Parsing uses regex patterns, which works reliably across platforms but may miss edge cases in complex syntax.
 
 ---
 
 ## CLI Commands
 
 ```bash
-# Quick setup (auto-configures AI tools)
-neuronlayer init
+neuronlayer init              # Set up project + configure AI tools
+neuronlayer serve             # Start HTTP API server
+neuronlayer projects list     # List registered projects
+neuronlayer projects add .    # Add current directory
+neuronlayer projects switch   # Switch active project
+neuronlayer export            # Export decisions to ADR files
+neuronlayer help              # Show help
+```
 
-# Initialize specific project
-neuronlayer init /path/to/project
+---
 
-# List all registered projects
-neuronlayer projects list
+## HTTP API
 
-# Add a new project
-neuronlayer projects add /path/to/my-project
+For tools that don't support MCP, NeuronLayer provides a REST API:
 
-# Switch active project
-neuronlayer projects switch <id>
+```bash
+neuronlayer serve --project /path/to/project --port 3333
+```
 
-# Export decisions to ADR files
-neuronlayer export --format madr
+**Endpoints:**
 
-# Show help
-neuronlayer help
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/status` | Project stats |
+| GET | `/search?q=...` | Semantic code search |
+| GET | `/dependencies?file=...` | File dependencies |
+| GET | `/impact?file=...` | Impact analysis |
+| GET | `/circular` | Find circular deps |
+| GET | `/decisions` | List decisions |
+| POST | `/decisions` | Record a decision |
+| GET | `/symbols?file=...` | Get file symbols |
+
+**Example:**
+```bash
+curl "http://localhost:3333/impact?file=src/auth/login.ts"
 ```
 
 ---
 
 ## Manual Configuration
 
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
+If `neuronlayer init` doesn't work for your setup, add to your Claude Desktop config:
 
 ```json
 {
@@ -236,67 +174,26 @@ Config locations:
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Linux**: `~/.config/claude/claude_desktop_config.json`
 
-### OpenCode
-
-Add to `~/.opencode/config.json`:
-
-```json
-{
-  "mcpServers": {
-    "neuronlayer": {
-      "command": "npx",
-      "args": ["-y", "neuronlayer", "--project", "/path/to/your/project"]
-    }
-  }
-}
-```
-
 ---
 
 ## Data Storage
 
-Each project has isolated data:
+Project data is stored locally:
 
 ```
 ~/.memorylayer/
 ├── projects/
-│   ├── project-a-abc123/
-│   │   ├── memorylayer.db    # SQLite database
-│   │   └── embeddings/       # Vector index
-│   └── project-b-def456/
-│       └── ...
-└── registry.json             # Project registry
+│   └── your-project-abc123/
+│       ├── neuronlayer.db    # SQLite database
+│       └── embeddings/       # Vector index
+└── registry.json             # Project list
 ```
 
 ---
 
-## NeuronLayer vs grep
-
-NeuronLayer **doesn't compete with grep** - Claude already has grep. They serve different purposes:
-
-| grep does | NeuronLayer does |
-|-----------|------------------|
-| Text matching | **Semantic search** ("how does auth work here?") |
-| Regex patterns | **Persistent memory** (decisions survive across sessions) |
-| Fast file search | **Architectural awareness** (knows module relationships) |
-| | **Pattern learning** (learns your coding conventions) |
-| | **Context preservation** (survives conversation resets) |
-
-**Real-world indexing** (Express.js - 141 files, 21k LOC):
-- First-time indexing: ~28 seconds (one-time for new codebases)
-- Subsequent sessions: Only changed files re-indexed (content hash check)
-- Index persists in SQLite between sessions
-
-**Use grep for:** "find all files containing `router`"
-**Use NeuronLayer for:** "how does the routing system work?" or "what decisions were made about authentication?"
-
----
-
 ## Privacy
 
-NeuronLayer is **100% local**:
-
-- All data stored on your machine
+- All data stays on your machine
 - No cloud services
 - No telemetry
 - Works offline
@@ -306,32 +203,20 @@ NeuronLayer is **100% local**:
 ## Development
 
 ```bash
-# Clone
 git clone https://github.com/abhisavakar/neuronlayer.git
 cd neuronlayer
-
-# Install
 npm install
-
-# Build
 npm run build
-
-# Type check
-npm run typecheck
 ```
 
 ---
 
 ## License
 
-MIT License - see [LICENSE](LICENSE)
+MIT - see [LICENSE](LICENSE)
 
 ---
 
-## Author
-
-**Abhishek Arun Savakar** - [savakar.com](https://savakar.com)
-
----
+**Author:** Abhishek Arun Savakar - [savakar.com](https://savakar.com)
 
 Built with [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic.