<p align="center">
  <img src="./agent-project-intelligence.png" alt="Agent Project Intelligence" width="100%" />
</p>

<h1 align="center">Agent Project Intelligence</h1>

<p align="center">
  <strong>Deterministic Cognitive Infrastructure for AI Coding Agents (Codex, Antigravity, Claude Code, Cursor, DeepSeek & more)</strong>
</p>

<p align="center">
  <b>English</b> | <a href="./README_zh.md">🇨🇳 简体中文</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Architecture-Tri--Pillar-blue.svg" alt="Tri-Pillar">
  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
  <img src="https://img.shields.io/badge/Protocol-MCP%20Stdio-purple.svg" alt="MCP">
  <img src="https://img.shields.io/badge/Node.js-%3E%3D20-orange.svg" alt="Node.js">
</p>

---

## 🎯 What Problem Does This Solve? Why Agent Project Intelligence?

Large Language Models (LLMs) write impressive code, but during long-term engineering iterations and real-world codebase development, both human developers and AI assistants confront four costly dilemmas:

### 1. Blind Grep & Token Drain in Every New Session
When assigned a new task, traditional agents (like Claude Code, Codex, Antigravity, and Cursor) mechanically repeat: `ls → grep → read full file → find symbol → find callers → guess dependencies`. Ingesting dozens of full files burns tens of thousands of tokens per turn and frequently leads to hallucinations, missing deep call paths, or overlooking cross-module side effects.
> **Solution**: Agent Project Intelligence parses your codebase using native **Tree-sitter ASTs** stored in SQLite WAL. The AI accesses exact symbols, signatures, callers/callees, and dependencies in sub-5ms—**zero LLM inference overhead, providing an instant ~500-token Bounded Context Pack**.

### 2. The "Design Document Graveyard" & Cognitive Drift (For Humans & AI Alike)
Real-world engineering involves not only code, but also evolving Markdown specifications and architectural blueprints. Developers frequently brainstorm features with AI (e.g. ChatGPT / Claude), generating a flurry of files: `proposal_v1.md`, `new_design.md`, and `refactor_final_v2.md`. This triggers a dangerous **double cognitive failure**:
- **Developer Cognitive Overload & Amnesia**: As Markdown files pile up, developers themselves lose track of which document represents the *currently active source of truth*. Particularly when branching off to implement a new feature or refactor, it is easy to forget or stray from the original core boundaries and constraints defined in early specs, only discovering irreconcilable architectural conflicts after the branch is finished;
- **AI Lacks Timeline Awareness & Overwrites Production**: LLMs have no intrinsic sense of chronological order across files. An AI agent will easily confuse historical drafts with current requirements, and might treat an unverified brainstorming proposal as absolute fact, generating destructive code that overturns stable production systems.
> **Solution**: A structured **Knowledge Lifecycle Graph and Truth Gate**.
> - **Stable Digital Identity (Stable Node ID)**: Uses immutable identifiers (`D-037` Design, `P-052` Proposal, `ADR-014` Decision). Iterations update the same file (version history is tracked by Git), eliminating `v1/v2/v3` graveyard sprawl at the root;
> - **Strict Lifecycle State Machine**: Clearly demarcates `DRAFT` → `REVIEW` → `ACTIVE` (current production truth) → `SUPERSEDED` → `ARCHIVED`;
> - **`ingest_document` Truth Gate**: Newly ingested external documents default to non-truth! The engine compares them against active designs, immediately flagging conflicts and downgrading them into Proposals, ensuring only human-reviewed specifications enter the active truth layer.

### 3. Session Amnesia, Disconnected Specs & The Zero-Loss Handoff Protocol
Complex engineering features often span days, requiring dozens or hundreds of conversational turns. However, context windows are finite and expensive, and as turns accumulate, model attention drifts or prompts crash and restart, creating two critical hurdles:
- **Session Reset Amnesia**: Whenever a new session starts or an IDE restarts, the agent is wiped clean. Discovered root causes, hard-fought gotchas, test evidence chains, and verified hypotheses vanish, forcing developers to waste time repetitively re-explaining the entire project background;
- **Specs and Code Are Siloed**: Specifications live in Markdown; code lives in source files. Changing a requirement cannot deterministically reveal affected functions, and modifying a low-level method cannot trace back to the impacted business logic.
> **Solution**: A **Cross Graph (Doc ↔ Symbol hard linkage)**, a **Current State Engine**, and an **Automated Handoff Protocol (`/handoff`)**:
> - **Bi-directional Navigation**: Frontmatter establishes verified links between documents and AST symbols (`D-037 IMPLEMENTED_BY CardPackService`). Changing a design reveals affected code immediately; modifying code triggers instant business impact analysis (`impact`);
> - **Zero-Loss Handoff Protocol (`/handoff`)**: When a session reaches its token budget, achieves a milestone, or switches windows, triggering `/handoff` serializes task objectives, landed code modifications, verification evidence (test/build outputs), architectural gotchas, and concrete Next Steps into `temp/HANDOFF.md`. A new agent aligns with this file first, **restoring 100% of the previous cognitive depth in 0 seconds with zero wasted tokens!**

### 4. Quantified ROI: ~85%+ Token Savings & 3x–5x Acceleration in Coding Velocity
In real-world mid-to-large codebases (10,000 to 100,000+ lines of code), deploying Project Intelligence delivers quantifiable gains in token economics and development throughput:
- **Token Consumption Slashed by ~80%–90%**:
  - *Traditional Mode*: Agents run `find` + blind `grep` and open 5 to 15 entire source files (500 to 2,000 lines each), burning **20,000 to 50,000+ tokens** just to comprehend the entry point.
  - *Project Intelligence*: Local Tree-sitter AST precomputations provide a compact **~500-token Bounded Context Pack** containing active state, related designs, and symbol signatures, followed by surgical line-span reads (`source("file.ts:10-40")`). Token consumption during project exploration is reduced by **80% to 90%**, slashing API bills and preventing context exhaustion.
- **3x–5x Acceleration in End-to-End Velocity**:
  - **Sub-5ms Deterministic Lookups**: Replaces slow, multi-turn LLM reasoning with instant SQLite index queries for callers, dependencies, and blast radius.
  - **Zero Cognitive Cold-Start Overhead**: Paired with the automated `/handoff` protocol, developers eliminate the 10-to-20-minute cognitive friction of re-explaining context whenever a session restarts or an IDE reboots, driving a **3x to 5x boost in practical implementation speed**.

---

## 🏛️ Tri-Pillar Architecture

```text
                               AI AGENTS
            (Codex / Antigravity / Claude Code / Cursor / DeepSeek)
                                   │
                                   ▼
                      ┌────────────────────────┐
                      │  Context Router (MCP)  │
                      └────────────┬───────────┘
                                   │
          ┌────────────────────────┼────────────────────────┐
          │                        │                        │
          ▼                        ▼                        ▼
 ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
 │ Knowledge Graph │      │   Code Graph    │      │  Current State  │
 │                 │      │                 │      │  & Handoff Log  │
 │ Design (ACTIVE) │      │ AST Symbols     │      │ Current Focus   │
 │ Proposal/Draft  │      │ Caller / Callee │      │ Stage & Blockers│
 │ ADR Decisions   │      │ Imports/Exports │      │ temp/HANDOFF.md │
 │ Truth Gate      │      │ Git Dirty Trace │      │ Next Steps      │
 └────────┬────────┘      └────────┬────────┘      └─────────────────┘
          │                        │
          └───────────┬────────────┘
                      ▼
             ┌─────────────────┐
             │   Cross Graph   │
             │ (Doc ↔ Symbol)  │
             └────────┬────────┘
                      ▼
       .project-intelligence/intelligence.db (SQLite)
```

1. **🌲 Deterministic Code Graph**:
   - Native multi-language Tree-sitter parsing (**TypeScript, JavaScript, Python, Rust**);
   - Extracts classes, interfaces, functions, methods, import edges (`IMPORTS`), call graphs (`CALLS`), and inheritance;
   - Blazing-fast SQLite WAL + FTS5 full-text search with PageRank symbol importance ranking;
   - Live filesystem watcher with incremental updates, Git dirty fingerprinting (no false-positive staleness), and diff deletion-matching.

2. **📄 Knowledge Lifecycle Graph & Truth Gate**:
   - Stable identification (`D-001` Design, `P-052` Proposal, `ADR-014` Architectural Decision Record);
   - Strict lifecycle state transitions: `DRAFT` → `REVIEW` → `ACTIVE` → `SUPERSEDED` → `ARCHIVED`;
   - Smart Ingestion Engine: detects overlap and conflicts with active truth, routing new proposals into review automatically.

3. **🧭 Current State, Cross Graph & Handoff Engine**:
   - Bi-directional navigation: traverse from high-level requirements directly to AST symbols (`D-037 IMPLEMENTED_BY CardPackService`);
   - Lightweight live state tracking: records current focus, active stage, blockers, and next steps;
   - **Handoff Protocol**: Serializes evidence and pending actions to `temp/HANDOFF.md` for seamless cross-session continuity.

---

## ⚡ Progressive Context Disclosure

The foundational philosophy: **never read a full file when a targeted slice is sufficient.**

```text
LEVEL 0: project_map()            ──> Inspect lightweight global module and design map
LEVEL 1: project_context(query)   ──> Fetch ~500-token Bounded Context Pack (State + Active Designs + Signatures)
LEVEL 2: symbol() / graph()       ──> Inspect exact symbol signatures, callers, callees, and dependencies
LEVEL 3: source("file.ts:10-40")  ──> Read the precise lines of implementation
LEVEL 4: read_file (fallback)     ──> Fallback to full file reading only when strictly necessary
```

---

## 🛠️ MCP Tool Matrix (11 Tools)

Project Intelligence runs as a standard Stdio MCP server exposing 11 high-level tools:

| Tool Name | Type | Description |
| :--- | :---: | :--- |
| `project_context` | 🔍 Read-only | **Primary Entry Point**. Returns compact ~500-token Bounded Context Pack for any task query |
| `project_map` | 🔍 Read-only | Generates a project-wide map of modules, active designs, and status |
| `symbol` | 🔍 Read-only | Looks up exact signature, line span, PageRank score, and related documentation |
| `graph` | 🔍 Read-only | Traverses call graphs, dependency trees, and cross-graph linkages with depth control |
| `impact` | 🔍 Read-only | Evaluates blast radius by symbol, file, or unified git diff hunks |
| `source` | 🔍 Read-only | Extracts exact code lines without reading full files (e.g. `file.ts:10-50`) |
| `knowledge` | 🔍 Read-only | Queries specific design documents, ADRs, and their formal relationships |
| `ingest_document` | ✍️ Mutation | **Truth Gate**. Ingests external Markdown with automatic collision detection |
| `decision_record` | ✍️ Mutation | Records architectural decisions, automatically creating standard `ADR-xxx.md` files |
| `state_update` | ✍️ Mutation | Updates live project focus, stage, blockers, and next steps |
| `lifecycle_transition`| ✍️ Mutation | Transitions design documents through lifecycle stages (e.g. promoting Proposal to ACTIVE) |

---

## 📂 Repository Directory Structure

```text
agent-project-intelligence/
├── dist/                      # Compiled production binaries (CLI & Stdio MCP Server)
│   ├── cli/index.js           # CLI executable entry point (`pi` command)
│   └── mcp/server.js          # Stdio MCP Server implementation
├── src/                       # TypeScript source code
│   ├── code/                  # Deterministic Code Graph Engine
│   │   ├── ast/               # Multi-language Tree-sitter AST visitors (TS/JS/Py/Rust)
│   │   ├── indexer.ts         # Code graph indexer (symbols, calls, imports)
│   │   └── watcher.ts         # Chokidar live file watcher with dirty fingerprinting
│   ├── knowledge/             # Document Lifecycle & Knowledge Graph Engine
│   │   ├── parser.ts          # YAML Frontmatter & markdown section parser
│   │   ├── indexer.ts         # Document indexer with parse-error process isolation
│   │   ├── ingest.ts          # Ingest conflict detection & proposal router
│   │   └── map.ts             # Lightweight project map generator
│   ├── cross/                 # Knowledge ↔ Code Cross-Graph Linker
│   │   └── linker.ts          # Bi-directional relations (IMPLEMENTS, AFFECTS, stale link purge)
│   ├── state/                 # Runtime State Engine
│   │   └── manager.ts         # Live focus, stage, blockers, and ADR automation
│   ├── mcp/                   # Model Context Protocol (MCP) Service Layer
│   │   ├── router.ts          # Bounded Context Pack router (~500 Token Context Pack)
│   │   └── server.ts          # 11 MCP tool registrations & permission annotation guards
│   ├── db/                    # SQLite Storage & Search Substrate
│   │   ├── database.ts        # SQLite WAL connection management & pragma optimization
│   │   ├── queries.ts         # Prepared statement cache & high-performance graph queries
│   │   └── schema.sql         # Unified relational schema, FTS5 tables, and sync triggers
│   └── config.ts              # Single-project sandboxing & path security verification
├── templates/
│   └── AGENTS.md              # Universal Agent behavior & context policy template
├── tests/                     # Comprehensive Vitest test suite (48/48 tests passing)
├── mcp-config-example.json    # Example configurations for Codex, Antigravity, Cursor, Claude
├── agent-project-intelligence.png  # Project architecture banner image
├── README.md                  # English official documentation
├── README_zh.md               # Chinese official documentation
├── LICENSE                    # MIT Open-Source License
└── package.json               # Package configuration and executable mappings
```

---

## 🚀 Quick Setup Across AI Agents

### 1. Google Antigravity (Project-Isolated Plugin)
In your target repository, create `.agents/plugins/project-intelligence/`:
- **`plugin.json`**: `{"name": "project-intelligence"}`
- **`mcp_config.json`**:
  ```json
  {
    "mcpServers": {
      "project-intelligence": {
        "command": "node",
        "args": ["/path/to/agent-project-intelligence/dist/cli/index.js", "serve", "."]
      }
    }
  }
  ```
- Copy `templates/AGENTS.md` to your target project's root directory.

### 2. OpenAI Codex
In your target repository, create `.codex/config.toml`:
```toml
[mcp_servers.project-intelligence]
command = "node"
args = ["/path/to/agent-project-intelligence/dist/cli/index.js", "serve", "."]
```

### 3. Claude Code
Run in your terminal:
```bash
claude mcp add project-intelligence -- node /path/to/agent-project-intelligence/dist/cli/index.js serve .
```
Copy `templates/AGENTS.md` to your target repository as `CLAUDE.md`.

### 4. Cursor / Windsurf / VSCode (Cline / Roo Code)
Add to your IDE's MCP configuration:
```json
{
  "mcpServers": {
    "project-intelligence": {
      "command": "node",
      "args": ["/path/to/agent-project-intelligence/dist/cli/index.js", "serve", "/absolute/path/to/target-project"]
    }
  }
}
```

### 5. DeepSeek Harness / CLI Pipelines (Non-MCP Environments)
Use the built-in CLI to inject structured context directly into prompt loops:
```bash
# Get targeted context for an implementation task
pi context "Implement user authentication token refresh"

# Inspect overall project map and blockers
pi map
pi state
```

---

## 💻 CLI Usage (`pi`)

In addition to serving as an MCP backend, `agent-project-intelligence` comes with a standalone CLI:

```bash
npm install -g agent-project-intelligence   # or build locally via `pnpm build`

pi init [dir]       # Initialize .project-intelligence database in target project
pi index [dir]      # Parse code and documentation into the database
pi serve [dir]      # Start Stdio MCP Server
pi watch [dir]      # Start live background file watcher
pi map [dir]        # Pretty-print module hierarchy and active designs
pi state [dir]      # View current development stage, focus, and blockers
pi ingest <file>    # Ingest external Markdown with conflict detection
```

---

## 💡 Prior Art & Acknowledgements

Agent Project Intelligence was engineered from the ground up as a comprehensive cognitive infrastructure for AI coding agents. We acknowledge the pioneering ideas from the open-source community that inspired our inception:

- [claude-ex](https://github.com/vihaanshahh/claude-ex): Inspired the approach of deterministic Tree-sitter AST symbol indexing, caller/callee graphs, and local SQLite caching.
- [open-codebase-index](https://github.com/opencode-ai/open-codebase-index): Inspired the bounded-context retrieval philosophy, branch-awareness, and low-token context packing.

Unlike pure code-indexing tools, Agent Project Intelligence integrates these concepts into an original **Tri-Pillar Architecture: Knowledge Lifecycle Graph + Deterministic Code Graph + Current State Engine + Cross-Session Handoff Protocol**.

---

## 📄 License

This project is licensed under the [MIT License](./LICENSE).