nexus-prime 0.2.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sir-ad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,253 +1,134 @@
 # 🧬 Nexus Prime
 
-**The AI meta-framework that makes agents smarter about themselves.**
-
-Nexus Prime is an MCP server that gives AI coding agents cross-session memory, token optimization, parallel sub-agent orchestration, and machine-checked guardrails — running as a background process that any agent can call as native tools.
+**The Self-Evolving Agent Operating System. Give your AI agent a brain that persists, thinks, and learns.**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://typescriptlang.org)
-[![npm](https://img.shields.io/npm/v/nexus-prime)](https://www.npmjs.com/package/nexus-prime)
-
----
-
-## The Super Intellect Stack
+[![Node.js](https://img.shields.io/badge/Node.js-22%2B-green.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://typescriptlang.org)
+[![Version](https://img.shields.io/badge/Version-1.2.0-orange.svg)](#-quickstart)
 
-Nexus Prime is the **runtime layer** in a 4-project ecosystem:
-
-```
-┌─────────────────────────────────────────────────┐
-│  Phantom (PM)                                    │
-│  "What to build" — PRDs, releases, docs         │
-│  github.com/sir-ad/phantom                      │
-├─────────────────────────────────────────────────┤
-│  MindKit (Skills)                                │
-│  "How to think" — 22 skills, guardrails, routing │
-│  github.com/sir-ad/mindkit                      │
-├─────────────────────────────────────────────────┤
-│  Nexus Prime (OS)  ← YOU ARE HERE               │
-│  "How to run" — memory, tokens, workers, POD     │
-│  github.com/sir-ad/nexus-prime                  │
-├─────────────────────────────────────────────────┤
-│  Grain (Language)                                │
-│  "How to speak" — 10 universal AI primitives     │
-│  github.com/sir-ad/grain                        │
-└─────────────────────────────────────────────────┘
-```
+> [!IMPORTANT]
+> **Nexus Prime** is a Meta-Framework exposed as an MCP (Model Context Protocol) server. It runs alongside your existing AI agents (Claude, Cursor, AntiGravity) to provide persistent memory, token optimization, and orchestrate parallel worker swarms.
 
 ---
 
-## Why?
+## 🎯 The Problem & Value Proposition
 
-Every AI coding session starts cold. The agent re-reads the same files, re-discovers the same patterns, makes the same mistakes. Nexus Prime fixes this:
+Every AI agent session starts with **total amnesia**. Your agent forgets yesterday's bug fix. It wastes 80% of its context window re-reading files it already understood. And when a task is complex enough to need multiple approaches, it works alone — sequentially, slowly.
 
-- **Memory persists between sessions** — findings survive restarts
-- **Token usage is optimized** — agents read only what they need (50-90% savings)
-- **Parallel sub-agents** explore multiple solutions simultaneously via git worktrees
-- **Guardrails prevent mistakes** before code is written
-- **Self-evolution** — learns from past sessions and adapts
+Nexus Prime gives your agent four superpowers:
 
----
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────┐
-│                   AI Agent (Claude / Gemini / GPT)   │
-│                                                       │
-│  Session Start         During Work          Shutdown  │
-│  nexus_recall_memory   nexus_store_memory   store     │
-│  nexus_memory_stats    nexus_optimize_tokens summary  │
-│                        nexus_mindkit_check            │
-│                        nexus_ghost_pass               │
-│                        nexus_spawn_workers            │
-│                        nexus_audit_evolution          │
-└────────────────────────┬────────────────────────────┘
-                         │ MCP (stdio)
-┌────────────────────────▼────────────────────────────┐
-│                   NEXUS PRIME MCP SERVER             │
-│                                                       │
-│  MemoryEngine          TokenSupremacyEngine           │
-│  ├─ Prefrontal (7)     ├─ Content-Aware Scoring       │
-│  ├─ Hippocampus (200)  ├─ BudgetAllocator             │
-│  └─ Cortex (∞, SQLite) └─ DifferentialContext        │
-│                                                       │
-│  PhantomWorkers        GuardrailEngine                │
-│  ├─ GhostPass          ├─ TokenBudget                 │
-│  ├─ PhantomWorker      ├─ DestructiveGuard            │
-│  ├─ MergeOracle        ├─ MindKit GitHub Sync         │
-│  └─ POD Network        └─ MemoryFirst                 │
-│                                                       │
-│  HyperTuning           AgentLearner                   │
-│  ├─ Adaptive Budget    ├─ SQL Pattern Detection        │
-│  └─ Complexity Signals └─ Evolution Candidates         │
-│                                                       │
-│  Embedder (TF-IDF 128-dim + optional OpenAI API)     │
-│  SessionTelemetry (📡 footer on every response)      │
-└─────────────────────────────────────────────────────┘
-         │
-         ▼
-    ~/.nexus-prime/memory.db  (SQLite, survives restarts)
-```
+| Superpower | What It Does |
+|:---|:---|
+| **🧠 Persistent Memory** | 3-tier knowledge system (Prefrontal → Hippocampus → Cortex). 820+ Zettelkasten links. Survives restarts. Automatically links related concepts. |
+| **⚡ Token Supremacy** | HyperTune™ optimizer reads only the relevant chunks. Continuous Attention Streams (CAS) compress discrete tokens into weighted continuous semantics. Saves 50-90% context. |
+| **🐝 Phantom Swarms** | Parallel workers in isolated Git Worktrees. Ghost Pass risk analysis → Spawn Parallel Workers → Byzantine Merge. |
+| **🛡️ MindKit Guardrails** | Machine-checked safety. Scores 0-100. Blocks destructive operations (like deleting test fixtures) before they happen. |
 
 ---
 
-## Quick Start
+## ⚡ 30-Second Quickstart
 
 ```bash
-# Install from npm
-npm install -g nexus-prime
-
-# Or clone and build
-git clone https://github.com/sir-ad/nexus-prime
-cd nexus-prime
-npm install
-npm run build
-```
+# Clone and build
+git clone https://github.com/sir-ad/nexus-prime.git
+cd nexus-prime && npm install && npm run build
 
-### Wire into your AI agent
+# Start the dashboard and background daemon
+npm run start
+```
 
-Add to your MCP config (AntiGravity, Claude Desktop, etc.):
+Add to your agent's MCP config (Cursor, Claude Desktop, etc.):
 
 ```json
 {
-  "mcpServers": {
-    "nexus-prime": {
-      "command": "node",
-      "args": ["/path/to/nexus-prime/dist/cli.js", "mcp"]
-    }
+  "nexus-prime": {
+    "command": "node",
+    "args": ["/absolute/path/to/nexus-prime/dist/cli.js", "mcp"]
   }
 }
 ```
 
----
+> [!TIP]
+> Once connected, ask your agent to call `nexus_memory_stats()` to confirm the cortex is online.
 
-## The 8 MCP Tools
-
-### Memory
-
-| Tool | When | What |
-|------|------|------|
-| `nexus_store_memory` | After discoveries | Store findings, bugs, decisions. Priority 0-1. |
-| `nexus_recall_memory` | Session start + mid-session | Semantic recall. Top-k memories matching query. |
-| `nexus_memory_stats` | Session start | Tier counts, top tags, Zettelkasten link stats. |
-
-### Intelligence
+---
 
-| Tool | When | What |
-|------|------|------|
-| `nexus_optimize_tokens` | Before reading 3+ files | Pre-flight reading plan. 50-90% token savings. |
-| `nexus_ghost_pass` | Before modifying 3+ files | Risk analysis + worker approach suggestions. |
-| `nexus_mindkit_check` | Before destructive ops | Guardrail check. PASS/FAIL with score 0-100. |
+## 📊 Real-Time Dashboard
 
-### Parallel Work
+Nexus Prime includes a **built-in visualization dashboard** powered by Server-Sent Events (SSE). Watch your agent's memory stores, token optimizations, phantom dispatches, and guardrail checks stream in real time — zero polling.
 
-| Tool | When | What |
-|------|------|------|
-| `nexus_spawn_workers` | Complex multi-file refactors | Phantom Workers in isolated git worktrees. |
-| `nexus_audit_evolution` | Sprint boundaries / post-bug | Find recurring patterns, file hotspots. |
+**Access it locally at:** `http://127.0.0.1:3377`
 
 ---
 
-## Memory System
+## 🧠 Core Primitives
 
-Three-tier architecture modelled on human memory:
+### Memory Tiers
+The fundamental unit of knowledge is a Memory, structured in 3 tiers (inspired by human cognition):
+- `prefrontal` — Active working memory, 7 items, instant recall.
+- `hippocampus` — Recent session context, ~200 items.
+- `cortex` — Long-term permanent storage backed by SQLite.
 
-| Tier | Size | Backed by | Purpose |
-|------|------|-----------|---------:|
-| **Prefrontal** | 7 items | RAM | Active working set |
-| **Hippocampus** | 200 items | RAM | Recent session context |
-| **Cortex** | Unlimited | SQLite | Long-term persistence |
+### Zettelkasten Linking
+Memories link to each other automatically when they share semantic context. High-priority stores trigger **fission** — the memory broadcasts to related existing memories, strengthening their links.
 
-**Recall** uses hybrid scoring: TF-IDF vectors (128-dim) + priority + recency + access count.
+### Context Compression (CAS Engine)
+The Continuous Attention Stream (CAS) Engine replaces discrete tokens with weighted continuous fluid potentials. Common patterns get compressed; novel information gets expanded. Achieves extreme context expansion.
 
 ---
 
-## Phantom Workers
+## 🛠️ MCP Tool API
 
-Parallel sub-agent framework using real git worktrees:
+Nexus Prime exposes powerful tools to the AI agent:
 
-```
-GhostPass (read-only analysis)
-  → N PhantomWorkers (parallel, isolated git worktrees)
-    → POD Network (asynchronous learning exchange)
-      → MergeOracle (Byzantine vote, confidence-weighted merge)
-```
+### `nexus_store_memory(content, priority, tags[])`
+Writes a memory to the prefrontal tier. If `priority ≥ 0.9`, it is auto-promoted to the Cortex. If `priority ≥ 0.8`, it generates Zettelkasten links.
 
-Each worker gets an isolated copy of the repo. Workers broadcast findings via the **POD Network**. The `MergeOracle` evaluates outcomes by confidence score.
+### `nexus_recall_memory(query, k)`
+Semantic nearest-neighbor search across all memory tiers. Uses hybrid scoring (`0.5×similarity + 0.25×priority + 0.15×recency + 0.1×access_bonus`).
 
----
+### `nexus_optimize_tokens(task, files[])`
+Analyzes files by relevance to the task, returning a structured reading plan (e.g., `full`, `outline`, or `skip`). Distributes the token budget securely.
 
-## Session Telemetry
+### `nexus_ghost_pass(goal, files[])`
+Read-only pre-flight analysis. Identifies risk areas (e.g., concurrent writes) and suggests parallel worker strategies before modifying files.
 
-Every MCP response includes a telemetry footer:
+### `nexus_spawn_workers(goal, files[])`
+Spawns parallel Phantom Workers in mathematically isolated Git Worktrees. Evaluates different implementation approaches simultaneously. Returns a `MergeDecision` from the Oracle to synthesize or apply the best approach.
 
-```
-─── 📡 Nexus Prime (12s) ───
-3 calls │ 20.3k tokens saved │ 2 stored │ 5 recalled │ 59 Zettel links
-```
+### `nexus_mindkit_check(action, filesToModify, isDestructive)`
+Evaluates high-risk actions against machine-checked Guardrail predicates. Returns `PASS/FAIL` and actionable suggestions to prevent disaster.
 
 ---
 
-## Guardrails (MindKit)
+## 🤖 Sub-Agent Roles
 
-6 machine-checked rules + external rules synced from [MindKit](https://github.com/sir-ad/mindkit):
+Nexus Prime manages a crew of specialized sub-agents:
 
-| Rule | Trigger | Action |
-|------|---------|--------|
-| `TOKEN_BUDGET` | Context > 100k tokens | 🚫 Block |
-| `TOKEN_WARN` | Context > 70k tokens | ⚠️ Warn |
-| `DESTRUCTIVE_GUARD` | `isDestructive: true` | 🚫 Block |
-| `BULK_FILE_GUARD` | > 10 files modified | ⚠️ Warn |
-| `NO_PROD_WRITES` | `/etc`, `/usr`, `/bin` | 🚫 Block |
-| `MEMORY_FIRST` | "research" / "look up" | ℹ️ Remind |
+| Role | Trigger Tool | Responsibility |
+|------|--------------|----------------|
+| **Ghost Pass Analyst** | `nexus_ghost_pass` | Reads AST, identifies risk areas, suggests approaches. |
+| **Phantom Worker** | `nexus_spawn_workers` | Executes tasks in isolated git worktrees independently. |
+| **Merge Oracle** | Post-worker | Byzantine vote on worker outputs, synthesizes winning diff. |
+| **Evolution Auditor** | `nexus_audit_evolution` | Scans memory for hotspots and recurring failure patterns. |
+| **Guardrail Enforcer**| `nexus_mindkit_check` | Machine-checks actions against Token Budget and Destructive rules. |
+| **Token Budgeteer** | `nexus_optimize_tokens` | Scores file relevance and builds optimized reading plans. |
+| **Memory Librarian** | `nexus_store_memory` | Promotes/demotes items across Prefrontal, Hippocampus, and Cortex. |
 
 ---
 
-## Project Structure
-
-```
-nexus-prime/
-├── src/
-│   ├── index.ts                    # NexusPrime main class
-│   ├── cli.ts                      # CLI entry (node dist/cli.js mcp)
-│   ├── agents/
-│   │   ├── adapters/mcp.ts         # MCP server, 8 tools + telemetry
-│   │   ├── coordinator.ts          # Worker dispatch orchestration
-│   │   ├── orchestrator.ts         # Context-aware agent runner
-│   │   └── learner.ts              # SQL-based evolution detection
-│   ├── engines/
-│   │   ├── memory.ts               # Three-tier memory + queryByTags
-│   │   ├── embedder.ts             # TF-IDF + optional OpenAI embeddings
-│   │   ├── token-supremacy.ts      # Content-aware token optimization
-│   │   ├── guardrails-bridge.ts    # GuardrailEngine + MindKit sync
-│   │   └── meta-learner.ts         # HyperTuning adaptive parameters
-│   └── phantom/
-│       ├── index.ts                # GhostPass, PhantomWorker, MergeOracle
-│       └── phase4-orchestrator.ts  # Self-built phase orchestrator
-├── packages/
-│   └── mindkit/                    # Standalone npm package
-├── test/
-│   ├── phantom.test.ts             # E2E Phantom Workers test
-│   └── memory.test.ts              # Semantic recall test
-├── GEMINI.md                       # Session protocol for AI agents
-├── AGENTS.md                       # Agent overview
-└── NEXUS.md                        # Language specification
-```
-
----
+## 🧩 Default Skill Cards
 
-## Configuration
+Skills are built-in behaviors the orchestrator can call upon:
 
-| Env Var | Default | Description |
-|---------|---------|-------------|
-| `NEXUS_EMBED_MODE` | `local` | `local` (TF-IDF) or `api` (OpenAI-compatible) |
-| `NEXUS_EMBED_URL` | — | API endpoint when mode=api |
-| `NEXUS_EMBED_KEY` | — | API key when mode=api |
-| `NEXUS_EMBED_MODEL` | — | Model name when mode=api |
+1. **`debug_typescript_error`**: Standard procedure for TS compiler errors. Triggers on "tsc error".
+2. **`optimize_token_budget`**: Drastic reduction of context usage. Triggers on "token limit" or "out of memory". Opens `nexus_optimize_tokens`.
+3. **`parallel_refactor`**: Uses `nexus_ghost_pass` and `nexus_spawn_workers` to explore refactoring strategies asynchronously.
+4. **`memory_first_research`**: Triggers `nexus_recall_memory` with high k to prevent re-researching solved problems.
 
 ---
 
-## License
+## 📜 License
 
-MIT — [sir-ad](https://github.com/sir-ad)
+Nexus Prime is released under the MIT License. See [LICENSE](LICENSE) for details.

package/dist/agents/adapters/mcp.d.ts

@@ -8,11 +8,13 @@ export declare class MCPAdapter implements Adapter {
     private server;
     private nexusRef?;
     private telemetry;
+    private sessionDNA;
     constructor();
     setNexusRef(nexus: NexusPrime): void;
     private setupToolHandlers;
     private handleToolCall;
-    private scanSourceFiles;
+    scanSourceFiles(cwd: string): string[];
+    private walk;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     send(_message: NetworkMessage): Promise<void>;

package/dist/agents/adapters/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/agents/adapters/mcp.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AA6C5C,qBAAa,UAAW,YAAW,OAAO;IACtC,IAAI,SAAS;IACb,IAAI,EAAG,KAAK,CAAU;IACtB,SAAS,UAAS;IAClB,MAAM,EAAE,MAAM,EAAE,CAAM;IAEtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,SAAS,CAA0B;;IAU3C,WAAW,CAAC,KAAK,EAAE,UAAU;IAI7B,OAAO,CAAC,iBAAiB;YAqIX,cAAc;IA8R5B,OAAO,CAAC,eAAe;IAgBjB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,IAAI,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IACnD,OAAO,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;CAC1C"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/agents/adapters/mcp.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAgK5C,qBAAa,UAAW,YAAW,OAAO;IACtC,IAAI,SAAS;IACb,IAAI,EAAG,KAAK,CAAU;IACtB,SAAS,UAAS;IAClB,MAAM,EAAE,MAAM,EAAE,CAAM;IAEtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,UAAU,CAAoB;;IAWtC,WAAW,CAAC,KAAK,EAAE,UAAU;IAI7B,OAAO,CAAC,iBAAiB;YA2RX,cAAc;IA8nB5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAItC,OAAO,CAAC,IAAI;IAmBN,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B,IAAI,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IACnD,OAAO,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;CAC1C"}