<div align="center">

# Xanther Context Engine (XCE)

### Your coding agent stops guessing.

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
[![PyPI](https://img.shields.io/pypi/v/xanther-xce)](https://pypi.org/project/xanther-xce)
[![SWE-bench Verified](https://img.shields.io/badge/SWE--bench%20Verified-78.2%25-brightgreen)](https://xanther.ai/benchmarks/)
![MCP Server](https://img.shields.io/badge/MCP-server-purple)

🌐 [xanther.ai](https://xanther.ai) &nbsp;·&nbsp; [Benchmarks](https://xanther.ai/benchmarks/) &nbsp;·&nbsp; [Docs](https://xanther.ai) &nbsp;·&nbsp; [XME — Memory Engine](https://github.com/Xanther-Ai/xanther-memory-engine)

</div>

---

> Your agent reads files one by one, forgets the architecture, and burns tokens re-deriving structure every session. XCE indexes your codebase into a multi-layer knowledge graph your agent queries over MCP — so it gets precise architectural context on every tool call instead of guessing.

**78.2% on SWE-bench Verified at $0.22/instance.** Works with Claude Code, Kiro, Cursor, Codex, and any MCP-compatible tool.

- **Multi-layer knowledge graph.** AST structure up to architecture docs, linked into one queryable graph (RAFT).
- **Semantic + structural search.** Find code by meaning or by symbol, across all four layers.
- **Impact analysis.** See the blast radius of a change before you make it — callers, dependents, affected modules.
- **Traceability.** Follow any symbol from code → component → architecture, or back down to the exact line.
- **MCP-native.** Five tools any agent can call. No custom pipeline per setup.
- **Cross-session memory (optional).** Bundle [XME](https://github.com/Xanther-Ai/xanther-memory-engine) so decisions and attempts persist across sessions.
- **Open source, self-hostable.** Neo4j runs locally in Docker. MIT licensed.

```bash
# Install both engines (XCE + XME) in one command
pip install "xanther-xce[all]"

xanther index /path/to/repo
xanther query "how does auth work?" --repo my-repo
```

---

## Why XCE

Coding agents are smart enough. They just lack context. The usual workarounds have limits:

- **Reading files one by one** starts from zero every session and burns tokens re-deriving structure.
- **Grep / keyword search** finds text matches with no understanding of relationships.
- **RAG / vector stores** return fuzzy chunks ranked by similarity and hope the model reconnects them.
- **LSP "go to definition"** answers one hop at a time — no impact analysis, no architecture view.

XCE takes a different path: **a persistent, multi-layer knowledge graph the agent traverses instead of re-reading source.**

- Structural relationships (calls, imports, inherits) are real graph edges, not guesses.
- LLM-generated docs (summaries, algorithms, architecture) let smaller models reason without reading raw code.
- Every answer traces to a symbol at a file and line you can open.
- Served over MCP, so any compatible agent gets it on every tool call with no agent changes.

---

## Prerequisites

Before you start, make sure you have these ready:

| Requirement | Required? | Purpose | How to get it |
|-------------|-----------|---------|---------------|
| **Python 3.9+** | ✅ Required | Runtime | `brew install python3` / [python.org](https://python.org) |
| **Docker** | ✅ Required | Runs Neo4j locally | [docker.com](https://docker.com) |
| **Neo4j 5.x** | ✅ Required | Knowledge graph + vector search | Via Docker (see Quick Start) |
| **OpenRouter API key** | ✅ Required for `full` mode | Embeddings + LLM doc generation (Layers 2–4) | [openrouter.ai/keys](https://openrouter.ai/keys) |
| **PostgreSQL** | ⬜ Optional | Incremental indexing state | Via Docker (`docker-compose up -d postgres`) |
| **OpenSearch** | ⬜ Optional | Episodic memory search (falls back to SQLite) | Via Docker |

> **⚠️ Important — OpenRouter API key**
>
> An **OpenRouter API key is required** for `full` mode indexing (which generates the L2–L4 documentation layers and vector embeddings) and for semantic search.
>
> 1. Sign up at **[openrouter.ai](https://openrouter.ai)**
> 2. Create a key at **[openrouter.ai/keys](https://openrouter.ai/keys)**
> 3. Add it to your `.env`:
>    ```bash
>    OPENROUTER_API_KEY=sk-or-v1-your-key-here
>    ```
>
> **Without an OpenRouter key** you can still run `--mode xme` (AST parse + memory sync only), which uses regex-based heuristics and needs no LLM. But you lose semantic search, doc generation, and the richer L2–L4 layers.

---

## Quick Start

### 1. Install

```bash
# Run instantly with uvx — bundles XCE + XME (no install needed)
uvx --from "xanther-xce[all]" xanther --help

# Or install with pip (includes XCE + XME memory engine)
pip install "xanther-xce[all]"

# Minimal install (XCE code intelligence only, no memory)
pip install xanther-xce

# Or from source
git clone https://github.com/Xanther-Ai/xanther-context-engine.git
cd xanther-context-engine
pip install -e ".[all]"
```

> The `[all]` extra bundles the **Xanther Memory Engine (XME)** alongside XCE — one command installs both engines together.

### 2. Infrastructure (Neo4j required)

```bash
# Neo4j (knowledge graph + vector search)
docker run -d --name xce-neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/xce_dev_password \
  neo4j:5-community
```

### 3. Configure

```bash
cp .env.example .env
```

Edit `.env` and set:

```bash
# Required
NEO4J_PASSWORD=xce_dev_password

# Required for `full` mode (embeddings + L2-L4 doc generation + semantic search)
# Get your key at https://openrouter.ai/keys
OPENROUTER_API_KEY=sk-or-v1-your-key-here
```

> If you skip the OpenRouter key, only `--mode xme` (AST + memory, no LLM) will work.

### 4. Index a repo

```bash
# Fast mode — AST parse + memory sync only (30s)
xanther index /path/to/repo --mode xme

# Full mode — all 4 layers + memory sync (5-20 min, resumable)
xanther index /path/to/repo --mode full
```

### 5. Query

```bash
xanther query "how does the auth middleware handle JWT tokens?" --repo my-repo
```

### 6. Visualize

```bash
xanther dashboard
# → http://localhost:8001
```

---

## E2E Setup Guide (Production)

### Prerequisites

| Component | Purpose | Install |
|-----------|---------|---------|
| Python 3.9+ | Runtime | `brew install python3` |
| Docker | Neo4j container | [docker.com](https://docker.com) |
| Neo4j 5.x | Graph + vector storage | Via Docker (see below) |
| OpenRouter API key | Embeddings + LLM docs | [openrouter.ai](https://openrouter.ai) |

### Step-by-Step Setup

```bash
# 1. Install Xanther
pip install xanther-xce

# 2. Start Neo4j
docker run -d --name xce-neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/xce_dev_password \
  -v xce_neo4j_data:/data \
  neo4j:5-community

# 3. Set environment variables
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=xce_dev_password
export OPENROUTER_API_KEY=sk-or-v1-your-key-here

# 4. Index your repository
xanther index ~/Projects/my-app --mode full

# 5. Verify
xanther status
```

### With XME (Cross-Session Memory)

For full memory capabilities, install the [Xanther Memory Engine](https://github.com/Xanther-Ai/xanther-memory-engine):

```bash
# Clone XME alongside XCE
git clone https://github.com/Xanther-Ai/xanther-memory-engine.git

# XCE auto-detects XME if it's a sibling directory
# Memory features are then available automatically
```

### Python API (Programmatic Setup)

```python
from xce.memory.setup import XCESetup

async def main():
    # One-liner setup (reads from env vars)
    xce = await XCESetup.create("/path/to/repo", repo_id="my-repo")

    # Query codebase
    ctx = await xce.query("how does auth work?")
    print(ctx["context_str"])  # LLM-ready context

    # Record what you learned
    await xce.record("fixed auth bug in middleware", files=["src/auth.py"])

    # Record architectural decisions
    await xce.decide("Use JWT for stateless auth", rationale="Scales horizontally")

    # Search past actions (cross-session memory)
    past = await xce.search_episodes("auth middleware fix")

    await xce.close()
```

### MCP Server (for Kiro, Claude Code, Cursor)

```bash
# Start as MCP server (stdio)
xce serve

# Start as SSE server (HTTP)
xce serve --sse --port 8000
```

Then connect your client. Pick yours:

<details>
<summary><b>Kiro</b></summary>

Add to `~/.kiro/settings/mcp.json` (global) or `.kiro/settings/mcp.json` (workspace):

```json
{
  "mcpServers": {
    "xanther-xce": {
      "command": "xce",
      "args": ["serve"],
      "env": { "NEO4J_PASSWORD": "your-password" },
      "autoApprove": ["xce_search", "xce_architecture_context", "xce_trace", "xce_impact_analysis"]
    }
  }
}
```
</details>

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add xanther-xce -- xce serve
```
</details>

<details>
<summary><b>Cursor</b></summary>

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "xanther-xce": {
      "command": "xce",
      "args": ["serve"],
      "env": { "NEO4J_PASSWORD": "your-password" }
    }
  }
}
```
</details>

<details>
<summary><b>VS Code</b></summary>

Add to your User Settings (JSON):

```json
{
  "mcp": {
    "servers": {
      "xanther-xce": {
        "command": "xce",
        "args": ["serve"],
        "env": { "NEO4J_PASSWORD": "your-password" }
      }
    }
  }
}
```
</details>

<details>
<summary><b>Anything MCP (HTTP / SSE)</b></summary>

Start XCE as an SSE server and point any MCP-over-HTTP client at it:

```bash
xce serve --sse --port 8000
```
</details>

Once connected, XCE exposes these MCP tools to your agent:

| Tool | Purpose |
|------|---------|
| `xce_architecture_context` | Architectural context for a file or symbol |
| `xce_search` | Search the knowledge graph (`semantic` \| `symbol` \| `tag`) |
| `xce_impact_analysis` | Predict the blast radius of proposed changes |
| `xce_trace` | Trace across abstraction levels (code ↔ component ↔ architecture) |
| `xce_index_repo` | Index / re-index a repository |

> See [`AGENTS.md`](AGENTS.md) for the recommended agent workflow — when to reach for each tool
> (orient with `xce_architecture_context`, check impact before editing, keep the graph fresh).

### Auto-Recording Hooks (XME Memory)

Install hooks to automatically record agent actions into XME memory. Every turn, tool call, and session end is captured for cross-session recall.

```bash
# Install hooks for Kiro + Claude Code
xce memory hooks install /path/to/repo

# Preview what would be installed (dry run)
xce memory hooks install /path/to/repo --dry-run

# Remove hooks
xce memory hooks uninstall /path/to/repo
```

**What gets installed:**

| Hook | Event | What it records |
|------|-------|----------------|
| `xme-session-end` | `agentStop` | Flush journal, compact, save session |
| `xme-record-turn` | `promptSubmit` | User turn in journal |
| `xme-record-tool` | `postToolUse` | Tool calls in journal |

**Or via Python API:**

```python
from xce.memory.setup import XCESetup

xce = await XCESetup.create("/path/to/repo")
xce.install_hooks()  # Installs Kiro + Claude Code hooks
```

After installation, every agent session automatically builds cross-session memory — no manual recording needed.

---

## Indexing Modes

| Mode | Time | What it does | When to use |
|------|------|-------------|-------------|
| `xme` | 30-60s | AST parse + embeddings + XME memory sync | Quick iteration, memory-focused |
| `full` | 5-20min | All 4 layers + embeddings + memory | First-time deep index |
| `xce` | 5-20min | Code graph only, no memory sync | Pure code intelligence |

### Indexing Layers Explained

```
Layer 1: AST Parse (tree-sitter)
  → Classes, functions, methods, imports
  → All languages: Python, TS, JS, Go, Rust, Java, Kotlin, C#, Ruby, Swift, C, C++
  → ~30 seconds for most repos

Layer 2: Component Summaries (LLM)
  → One-sentence description of each function/class
  → Dependencies and responsibilities
  → ~2-5 minutes

Layer 3: Detailed Documentation (LLM)
  → Algorithm descriptions, data flow, error handling, edge cases
  → Parallelized (10 workers by default, set XCE_LAYER3_WORKERS)
  → ~5-10 minutes

Layer 4: Architecture (LLM)
  → High-level design per module
  → Design patterns, integration points, quality attributes
  → ~2-5 minutes

Embeddings: Vector Encoding (OpenRouter)
  → 512-dimensional vectors for each node
  → Enables semantic search via Neo4j vector index
  → ~1-2 minutes
```

### Incremental & Resumable

```bash
# Only re-index changed files (default)
xanther index /path/to/repo

# Force full re-index
xanther index /path/to/repo --full

# Only git-changed files
xanther index /path/to/repo --diff

# If interrupted (Ctrl+C), just re-run — picks up where it left off
xanther index /path/to/repo --mode full
```

### Auto-Indexing on Commit (Git Post-Commit Hook)

Keep the knowledge graph in sync automatically — install a git **post-commit hook** that
incrementally re-indexes changed files after every commit. No more manual `xanther index` runs.

```bash
# Install the post-commit hook into a repo (defaults to fast xme mode)
xanther git-hook install /path/to/repo

# Preview what would be installed without writing anything
xanther git-hook install /path/to/repo --dry-run

# Choose the indexing mode the hook runs (xme | xce | full)
xanther git-hook install /path/to/repo --mode full

# Remove the hook
xanther git-hook uninstall /path/to/repo
```

**What the hook does:** after each `git commit`, it runs the following in the **background**
so it never blocks your commit flow, appending output to `.xanther/post-commit.log`:

```bash
xanther index <repo> --diff --mode xme
```

- **`--diff`** limits parsing to files changed in the commit (fast, incremental).
- **`--mode xme`** (default) keeps it quick: AST parse + embeddings + memory sync, **no LLM doc
  generation**. Use `--mode full` if you want the L2–L4 docs regenerated on every commit.

**Notes:**
- The hook is **idempotent** — re-installing replaces the prior Xanther block and preserves any
  existing `post-commit` hook content you already have.
- Works with git **worktrees and submodules** (resolves the real `.git` directory).
- Prefers the `xanther` executable from your active virtualenv, so it keeps working inside venvs.

### Smart Docs (Cost Optimization)

By default, Xanther skips generating LLM docs for trivial nodes (one-liners, getters/setters). This reduces LLM cost ~80% with minimal quality loss.

```bash
# Default (smart filtering ON)
xanther index /path/to/repo --mode full

# Generate docs for ALL nodes (slower, more expensive)
xanther index /path/to/repo --mode full --no-smart-docs
```

---

## CLI Commands

```bash
xanther index <path>              # Index a repository
xanther index <path> --mode xme   # Fast: AST + memory only (no LLM)
xanther index <path> --mode full  # Full: all layers + memory
xanther index <path> --mode xce   # XCE only (no memory sync)
xanther index <path> --diff       # Only index git-changed files
xanther index <path> --full       # Force re-index (no incremental)

xanther status                    # Show all indexed repositories
xanther dashboard                 # Launch graph visualization UI
xanther dashboard --port 8080     # Custom port

xanther query "question" --repo flask  # Query code memory

xanther git-hook install <path>   # Auto-index changed files after each commit
xanther git-hook uninstall <path> # Remove the post-commit hook

xanther memory hooks install <path>   # Auto-record agent sessions into XME memory
xanther memory hooks uninstall <path> # Remove the XME recording hooks
```

---

## Benchmarks (SWE-bench Verified)

| Model | Configuration | Resolve Rate | Cost/Instance |
|-------|--------------|--------------|---------------|
| Sonnet 4.0 (baseline) | mini-swe-agent | 66% | $1.50 |
| Sonnet 4.0 + XCE | Resolve@1 | **73.4%** | $1.20 |
| MiniMax M2.5 + XCE | SWE-bench Verified | **78.2%** | **$0.22** |
| Claude 4.5 Opus | Leaderboard | 76.8% | $8.50 |

**8,427 XCE tool calls** across 499 instances. Full results: [xanther.ai/benchmarks](https://xanther.ai/benchmarks/)

---

## How it works

You ask your agent to fix a bug in the auth flow. Instead of opening files at random, it queries XCE over MCP:

**1. Orient.** The agent calls `xce_architecture_context` on the auth module and gets the design back — role, patterns, integration points — without reading a single file.

```
Auth subsystem · Strategy + Decorator patterns
Integrates: user_service, token_manager, audit_logger
Entry: authenticate() → _validate() → token_gen()
```

**2. Check impact before editing.** Before changing `token_gen()`, it calls `xce_impact_analysis`:

```
token_gen() is called by 7 functions across 3 modules.
Affected tests: test_auth.py, test_session.py
⚠ session.refresh() depends on the current return shape.
```

**3. Make the change** knowing the blast radius — updating `session.refresh()` in the same pass instead of breaking it.

**4. Remember (with XME).** The decision and the fix are captured automatically. Next session, the agent recalls "we moved token_gen to HMAC-SHA256, and session.refresh depends on it" instead of relearning it.

Every answer traces to a symbol at a file and line you can open — the agent reasons over a graph, not a pile of guessed chunks.

---

## How it compares

Most tools that give agents "context" pick one lane — raw structure, or fuzzy retrieval, or one-hop navigation. XCE combines a real graph, LLM-generated docs, semantic search, and impact analysis, then serves them over MCP.

| | Grep / keyword | RAG / vector store | LSP (go to def) | Graph-only tools | **XCE** |
|--|---|---|---|---|---|
| Structural graph (calls/imports) | ❌ | ❌ | partial | ✅ | ✅ |
| Semantic search | ❌ | ✅ | ❌ | ❌ | ✅ |
| LLM-generated docs (L2–L4) | ❌ | ❌ | ❌ | ❌ | ✅ |
| Impact analysis (blast radius) | ❌ | ❌ | ❌ | partial | ✅ |
| Cross-abstraction traceability | ❌ | ❌ | ❌ | partial | ✅ |
| Cross-session memory | ❌ | ❌ | ❌ | ❌ | ✅ via XME |
| MCP-native tools | ❌ | varies | ✅ | varies | ✅ (5) |
| Answer traces to file:line | ✅ | ❌ | ✅ | ✅ | ✅ |
| Open source / self-hostable | ✅ | varies | ✅ | varies | ✅ (MIT) |

---

## Xanther Memory & Context Architecture

### XCE (Context Engine) — Code Intelligence

XCE indexes your codebase across 4 layers:

| Layer | Description | Output |
|-------|-------------|--------|
| **L1: AST** | Tree-sitter parsing of all source files | Classes, functions, methods, imports, dependencies |
| **L2: Summaries** | LLM-generated descriptions | One-sentence summaries of each symbol |
| **L3: Docs** | Detailed documentation | Algorithm, data flow, error handling, edge cases |
| **L4: Architecture** | Module-level design docs | High-level design, patterns, integration points |

**Key Features:**
- **4096+ relationships** tracked per large codebase (calls, imports, inherits, decorates)
- **512-dim vector embeddings** for semantic search
- **Impact analysis** to trace dependencies and predict change effects
- **Traceability** linking code to requirements and tests

### XME (Memory Engine) — Agent Memory

XME provides persistent, cross-session memory for agents:

| Layer | Description | Storage |
|-------|-------------|--------|
| **Episodic Store** | Session transcripts, tool calls, decisions | SQLite + OpenSearch |
| **Fact Graph** | Extracted facts (decisions, attempts, preferences) | Neo4j temporal |
| **Context Layer** | Live, updated facts during agent sessions | Redis-style |

**Key Features:**
- **Cross-session recall** — remember past agent actions across sessions
- **Hybrid search** — semantic + full-text over memories
- **Automatic hooking** — record agent actions automatically
- **Fact deduplication** — merge similar memories with configurable thresholds

### XCE → XME Bridge

The bridge syncs code facts from XCE into XME memory:

```
Indexed Code Facts → XME Episodic Store
  → Code symbols become queryable memories
  → Search "how does auth work?" returns both code facts + past sessions
```

**Benefits:**
- Memory contains code knowledge from indexing
- Search returns unified results (code + conversation)
- No need to re-index for memory updates

---

## Metrics & Statistics

### Real-World Indexing Stats

| Repository | Nodes | Edges | Index Time | Memory Used |
|------------|-------|-------|------------|-------------|
| httpx | 2,392 | 4,213 | 142s | 1.2GB |
| Flask | 2,895 | 5,095 | 168s | 1.5GB |
| FastAPI | 1,523 | 3,102 | 118s | 0.9GB |
| Express | 253 | 150 | 42s | 0.3GB |
| Celery | 3,102 | 6,234 | 203s | 2.1GB |
| **Sympy** | **114,240** | **604,776** | **2,845s** | **12.5GB** |

### Performance Benchmarks

| Operation | Time (httpx) | Time (Flask) | Time (Sympy) |
|-----------|--------------|--------------|--------------|
| L1 AST Parse | 32s | 38s | 210s |
| L2 Summaries | 48s | 56s | 320s |
| L3 Detailed Docs | 62s | 72s | 415s |
| L4 Architecture | 38s | 44s | 280s |
| Embeddings | 28s | 34s | 195s |
| **Total** | **208s** | **244s** | **1,420s** |

### Memory Efficiency

| Feature | Memory | CPU | Storage |
|---------|--------|-----|---------|
| Indexed graph (httpx) | 1.2GB | 1.5 cores | 450MB |
| Cross-session memory (100 sessions) | +0.8GB | +0.2 cores | +200MB |
| Concurrent queries (5) | +0.5GB | +0.8 cores | - |

---

## Examples

### Example 1: Understanding a New Codebase

```bash
# Install and index a new project
xanther index ~/Projects/my-new-project --mode full

# Query to understand the architecture
xanther query "How does the authentication flow work?" --repo my-new-project

# Get specific function details
xanther query "What does the PaymentProcessor.process() method do?" --repo my-new-project

# Find related components
xanther query "What files depend on the database module?" --repo my-new-project
```

### Example 2: Agent Integration (Python)

```python
import asyncio
from xce.memory.setup import XCESetup

async def main():
    # Setup with cross-session memory
    xce = await XCESetup.create(
        path="/path/to/repo",
        repo_id="my-app",
        mode="full"  # Enables XME bridge
    )
    
    # First session - learn the codebase
    ctx = await xce.query("What is the entry point?")
    print(f"Context: {ctx['context_str'][:200]}...")
    
    # Record what we learned
    await xce.record(
        "Entry point is main.py, uses FastAPI app instance",
        files=["src/main.py"]
    )
    
    # Second session - same memory persists!
    ctx2 = await xce.query("What framework is used?")
    # Memory includes: FastAPI app instance, main.py entry point
    
    # Search past sessions
    past = await xce.search_episodes("FastAPI", top_k=3)
    print(f"Found {len(past)} relevant past sessions")
    
    await xce.close()

asyncio.run(main())
```

### Example 3: Impact Analysis

```bash
# Find all callers of a function
xanther query "Who calls auth.middleware()?" --repo my-app

# Get impact before making changes
xanther query "What would break if I change the User model?" --repo my-app

# Find test coverage
xanther query "Which tests cover the payment processor?" --repo my-app
```

### Example 4: Dashboard Visualization

```bash
# Launch the dashboard
xanther dashboard

# Open http://localhost:8001 in browser
# - Click nodes to see details
# - Toggle layers L1-L4
# - Search for symbols
# - Export graph visualization
```

### Example 5: Automatic Hooking

```bash
# Install hooks for automatic memory recording
xanther memory hooks install ~/Projects/my-app

# Now any agent session automatically records:
# - User prompts
# - Tool calls
# - Decisions made
# - Files modified

# View recorded sessions
xanther status  # Shows indexed repos AND recorded sessions

# Search across sessions and code
xanther query "How did we fix the auth bug last week?" --repo my-app
# Returns: Code facts about auth + Session where fix was discussed
```

---

```
┌─────────────────────────────────────────────────────────┐
│                    xanther CLI                           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  XCE (Code Intelligence)         XME (Agent Memory)     │
│  ├─ Layer 1: AST Parse           ├─ Episodic Store      │
│  │  (tree-sitter, all langs)     │  (sessions, actions) │
│  ├─ Layer 2: Summaries           ├─ Fact Graph          │
│  │  (LLM descriptions)           │  (Neo4j temporal)    │
│  ├─ Layer 3: Detailed Docs       └─ Context Layer       │
│  │  (algorithm, data flow)          (live UPSERT)       │
│  ├─ Layer 4: Architecture                               │
│  │  (HLD per module)                                    │
│  └─ Embeddings (vector search)                          │
│                                                         │
│  XME Bridge: syncs code facts → memory                  │
│  CodeMemory: unified query interface                    │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  Storage: Neo4j (graph) + SQLite (episodes) + OpenSearch│
│  Dashboard: localhost:8001/graph.html (vis-network)      │
└─────────────────────────────────────────────────────────┘
```

## Graph Visualization

Launch the dashboard with `xanther dashboard` and open **http://localhost:8001** to explore your codebase as an interactive knowledge graph:

![Xanther Graph Visualization](docs/images/graph-visualization.png)

The graph explorer provides:

- **Interactive force-directed graph** of your codebase
- **Layer toggles:** L1 (AST) → L2 (Descriptions) → L3 (Docs) → L4 (Architecture)
- **Code Facts** — structural knowledge from indexing
- **Agent Memory** — decisions and actions from agent sessions
- **Color by Module** — clusters files by directory
- **Hierarchy view** — top-down L4→L3→L2→L1 layout
- **Search** — find and focus on any symbol
- **Click** any node for detailed info panel

---

## Supported Languages

Python, TypeScript, JavaScript, Go, Rust, Java, Kotlin, C#, Ruby, Swift, C, C++

---

## Environment Variables

See `.env.example` for full documentation. Key ones:

```bash
# Required
NEO4J_PASSWORD=xce_dev_password
OPENROUTER_API_KEY=sk-or-...       # for doc generation + embeddings

# Optional
XCE_DEEP_DOCS=true                 # Layer 3 (default: on)
XCE_ARCH_DOCS=true                 # Layer 4 (default: on)
XME_BRIDGE_ENABLED=true            # XME memory sync (default via --mode)
XCE_LLM_PROVIDER=openrouter        # force OpenRouter over AWS Bedrock
```

---

## API (for integrations)

When the dashboard is running:

```bash
GET /api/graph/repos                          # list indexed repos
GET /api/graph/nodes?repo_id=flask&limit=500  # AST nodes
GET /api/graph/edges?repo_id=flask&limit=1000 # edges (CALLS, IMPORTS, INHERITS)
GET /api/graph/layers?repo_id=flask&limit=300 # all layers (L1-L4 + memory)
```

---

## Project Structure

```
xce/
├── cli/interactive.py      # xanther CLI (index, status, dashboard, query)
├── indexing/
│   ├── indexer.py          # multi-layer indexing pipeline
│   ├── checkpoint.py       # resumable progress tracking
│   ├── doc_generator.py    # LLM doc generation (Layers 2-4)
│   └── embedding.py        # vector encoding
├── parsers/                # tree-sitter language parsers
├── git_hooks.py            # post-commit auto-index hook installer
├── graph/store.py          # Neo4j graph operations
├── memory/
│   ├── xme_bridge.py       # XCE → XME fact sync
│   └── code_memory.py      # unified query interface
├── dashboard/
│   ├── server.py           # FastAPI backend (30 routes)
│   ├── static/graph.html   # standalone graph visualization
│   └── ui/                 # React frontend (legacy)
└── models.py               # ASTNode, ComponentDesc, ArchitectureDoc
```

---

## License

MIT

## Links

- **Website:** [xanther.ai](https://xanther.ai)
- **Benchmarks:** [xanther.ai/benchmarks](https://xanther.ai/benchmarks/)
- **XCE (this repo):** [github.com/Xanther-Ai/xanther-context-engine](https://github.com/Xanther-Ai/xanther-context-engine)
- **XME (memory engine):** [github.com/Xanther-Ai/xanther-memory-engine](https://github.com/Xanther-Ai/xanther-memory-engine)
- **PyPI (XCE):** [pypi.org/project/xanther-xce](https://pypi.org/project/xanther-xce/)
- **PyPI (XME):** [pypi.org/project/xanther-xme](https://pypi.org/project/xanther-xme/)

---

## Community & Support

- **Discord:** Join our community for help and discussions
- **GitHub Issues:** Report bugs and suggest features
- **Documentation:** See `docs/` folder for detailed guides

---

**Built for agents. Powered by code.**