# 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

# 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]"

# 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

cp .env.example .env

# 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

# 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

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

xanther dashboard
# → http://localhost:8001

# 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

# 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

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()

# Start as MCP server (stdio)
xce serve

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

{
  "mcpServers": {
    "xanther-xce": {
      "command": "xce",
      "args": ["serve"],
      "env": { "NEO4J_PASSWORD": "your-password" },
      "autoApprove": ["xce_search", "xce_architecture_context", "xce_trace", "xce_impact_analysis"]
    }
  }
}

claude mcp add xanther-xce -- xce serve

{
  "mcpServers": {
    "xanther-xce": {
      "command": "xce",
      "args": ["serve"],
      "env": { "NEO4J_PASSWORD": "your-password" }
    }
  }
}

{
  "mcp": {
    "servers": {
      "xanther-xce": {
        "command": "xce",
        "args": ["serve"],
        "env": { "NEO4J_PASSWORD": "your-password" }
      }
    }
  }
}

xce serve --sse --port 8000

# 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

from xce.memory.setup import XCESetup

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

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

# 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

# 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

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

# 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

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

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

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.

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

# 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

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())

# 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

# 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

# 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)      │
└─────────────────────────────────────────────────────────┘

# 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

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)

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