🧠 Context-Architect

Universal Autonomous Context Window Management, Prompt Caching, Token Optimization & Observability AI Skill Agent
Slash LLM API costs by 80%–90%, guarantee ≥85% prompt cache hits, eliminate Lost-in-the-Middle degradation, and monitor context telemetry in real time across any IDE and any AI Agent.

English | Bahasa Indonesia

🌟 Overview

Context-Architect is an industrial-grade autonomous skill agent and MCP server engineered to eliminate LLM context window exhaustion, prevent cognitive degradation (Lost-in-the-Middle phenomenon), maximize KV-cache reuse, and provide end-to-end token observability for autonomous coding agents.

Operating with zero external dependencies on native Node.js (v18+), Context-Architect dynamically slices massive codebases, collapses verbose logs/diffs, manages a 3-tier memory hierarchy, and enforces deterministic prompt layouts—enabling AI agents to maintain lightning-fast response times and up to 90% token cost reduction.

Core Highlights:

• 🚀 Zero External Dependencies: Pure native Node.js ES Module with sub-45ms execution latency. No external compiler or tree-sitter binaries needed.

• ⚡ 80%–90% Token Reduction: Zero-compiler AST structural skeletonization and Just-in-Time (JIT) line-range hydration.

• 💰 Deterministic KV-Cache Freezing: Invariant prefix ordering guaranteeing ≥85%–95% prompt cache hit rates on Claude 3.7/3.5 Sonnet, Gemini 2.0/1.5, DeepSeek-V3, and OpenAI GPT-4o.

• 🎯 Lost-in-the-Middle Elimination: Dual-Anchor layout (Primacy at Head, Recency at Tail) ensuring 100% adherence to critical constraints.

• ⏪ Tree-of-Thought State Rewind: Snapshot save & instant rollback preventing context pollution during failed exploration loops.

• 🛡️ Subagent Micro-Capsule Sandboxing: Strict <8k token scoping for multi-agent swarms (LangGraph, AutoGen, CrewAI).

• 📊 Built-in Live Observability Sub-Engine: Real-time ASCII/ANSI terminal TUI dashboard and standalone responsive HTML/SVG reports.

• 🌐 100% Universal Agent Compatibility: 11 Native MCP tools and seamless adapters for Google Antigravity, Cursor, Claude Code, Windsurf, Kiro, Copilot, Cline, and Continue.dev.

Related MCP server: GraphHub

🏛️ System Architecture

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
graph TB
    subgraph ClientLayer ["1. Universal Agent & IDE Layer"]
        A1["Google Antigravity<br/>(@context-architect)"]
        A2["Cursor<br/>(.cursor/rules/*.mdc)"]
        A3["Claude Code<br/>(CLAUDE.md)"]
        A4["Windsurf<br/>(.windsurfrules)"]
        A5["Kiro IDE<br/>(.kiro/steering/*.md)"]
        A6["VS Code / Copilot<br/>(.github/copilot-instructions)"]
        A7["Roo Code / Cline<br/>(.clinerules)"]
        A8["Continue.dev<br/>(.continue/rules/*.md)"]
        A9["Multi-Agent Swarms<br/>(LangGraph / AutoGen / CrewAI)"]
    end

    subgraph CoreEngine ["2. Context-Architect Core Orchestrator"]
        C1["MCP JSON-RPC Protocol & CLI Dispatcher"]
        C2["Tokenizer & Pareto Budget Allocator"]
        C3["Early Warning Pressure Gauge (Green/Amber/Red/Panic)"]
    end

    subgraph SevenPillars ["3. The 7 Optimization Pillars"]
        P1["P1: Token Telemetry<br/>& Cost Model"]
        P2["P2: AST JIT Slicing<br/>& Skeletonizer"]
        P3["P3: Log & Diff<br/>Collapser"]
        P4["P4: Tri-Tier Memory<br/>& Semantic GC"]
        P5["P5: KV-Cache Prefix<br/>Freezing"]
        P6["P6: State Rewind &<br/>Subagent Sandbox"]
        P7["P7: Stream Guard &<br/>Secret Scrubber"]
    end

    subgraph ObservabilityLayer ["4. Observability & Layout Sub-Engine"]
        O1["Dual-Anchor Layout Assembler (Head 15% / Mid 70% / Tail 15%)"]
        O2["Live Terminal TUI Dashboard"]
        O3["Standalone HTML / Markdown Telemetry Reports"]
    end

    ClientLayer --> CoreEngine
    CoreEngine --> SevenPillars
    SevenPillars --> ObservabilityLayer

Architecture Narrative (WCAG 2.2 AA Textual Description):

1. Universal Agent Layer: AI assistants (Antigravity, Cursor, Claude Code, Windsurf, Kiro, Copilot, Cline, Continue.dev, LangGraph, AutoGen) send execution contexts and prompts to the Context-Architect Core Orchestrator.

2. Core Orchestrator: The MCP JSON-RPC protocol router, Universal Tokenizer, and Early Warning Pressure Gauge evaluate token pressure (Green, Amber, Red, Panic) and assign optimal Pareto budgets across system invariants, active code, history, memory, and output headroom.

3. The 7 Optimization Pillars:

   • Pillar 1 (Telemetry) calculates real-time token consumption across models (cl100k, o200k, Gemini, Claude, Llama).

   • Pillar 2 (AST Slicing) creates zero-compiler AST skeletons and hydrates focused line ranges Just-in-Time.

   • Pillar 3 (Compression) collapses repetitive test logs and minimalizes unified git diffs.

   • Pillar 4 (Memory) manages Hot Working Memory, Warm Episodic Fact Anchors, and Cold Archival Store with native BM25 search.

   • Pillar 5 (Prompt Caching) enforces deterministic static prefix freezing for 100% cache hits.

   • Pillar 6 (Branching) enables Tree-of-Thought state snapshots, rewind, and subagent micro-capsule sandboxing.

   • Pillar 7 (Guardrails) clamps tool output buffers and redacts sensitive credentials.

4. Observability Sub-Engine: The Dual-Anchor Layout Assembler places critical directives at the Head (15%) and immediate user objectives at the Tail (15%) with middle code skeletons (70%), accompanied by Live Terminal TUI Dashboards and interactive HTML telemetry reports.

🔠 Supported Language Profiles

Context-Architect includes native, zero-compiler language profiles for all major ecosystems:

🎯 Choose Your Integration Method

Context-Architect offers three equal, high-fidelity integration paths:

🚀 Quick Start

💬 Method A: AI Agent Chat via MCP (Recommended — Requires Node.js)

Add Context-Architect directly to your AI IDE (Cursor, Claude Desktop, Google Antigravity, Windsurf, Kiro, Continue.dev, etc.) via MCP:

{
  "mcpServers": {
    "context-architect": {
      "command": "npx",
      "args": [
        "-y",
        "github:hanifalkauni/context-architect",
        "--mcp"
      ]
    }
  }
}

Now prompt your AI assistant naturally in chat:

"@context-architect inspect current token consumption and optimize our prompt layout"
(or: "slice src/services/PaymentService.ts to skeleton and focus on processPayment()")

The agent autonomously invokes the native MCP tools, optimizes the context window, and isolates root cause errors—no manual intervention needed!

📄 Method B: Pure Skill Agent / Rule File (No Node.js Required)

If you don't have Node.js running as an MCP background daemon, you can still use Context-Architect with 100% fidelity by adding the rule/skill adapter directly into your project:

🌐 Option 1: Automatic via skills.sh (Recommended — 30+ AI Agents)

Install with a single command directly into Cursor, Claude Code, Windsurf, Copilot, or Gemini CLI:

npx skills add hanifalkauni/context-architect

⚡ Option 2: Automatic Adapter Injection via CLI

Run this command in any target project root to export all agent adapters automatically:

npx -y github:hanifalkauni/context-architect init

📦 Option 3: Manual Installation per AI Agent

Copy adapter to local workspace skill directory:

mkdir -p .agents/skills/context-architect
cp adapters/antigravity/SKILL.md .agents/skills/context-architect/SKILL.md

Or install globally for all workspaces at: ~/.gemini/config/skills/context-architect/SKILL.md.

Copy rules to your Cursor directory:

mkdir -p .cursor/rules
cp adapters/cursor/context-architect.mdc .cursor/rules/context-architect.mdc

Copy steering file and MCP configuration to your Kiro project:

mkdir -p .kiro/steering
cp adapters/kiro/context-architect.md .kiro/steering/context-architect.md
# (Optional) For MCP mode in Kiro:
cp adapters/kiro/config.json .kiro/config.json

Copy instructions to your project root:

cp adapters/claude/CLAUDE.md ./CLAUDE.md

For Claude Desktop, configure the MCP server using Method A above.

Copy rules to your repository root:

cp adapters/windsurf/.windsurfrules ./.windsurfrules

Copy instructions to your GitHub configuration directory:

mkdir -p .github
cp adapters/copilot/copilot-instructions.md .github/copilot-instructions.md

Copy rules to your project root:

cp adapters/cline/.clinerules ./.clinerules

Copy rules and configuration to your Continue directory:

mkdir -p .continue/rules
cp adapters/continue/context-architect.md .continue/rules/context-architect.md
# (Optional) For MCP mode in Continue:
cp adapters/continue/config.json .continue/config.json

Import the Python or TypeScript middleware directly into your multi-agent workflow:

• TypeScript: adapters/frameworks/langgraph.ts

• Python: adapters/frameworks/autogen.py or adapters/frameworks/crewai.py

Your AI Agent will read the rule file and enforce the 7 Pillars of Context Optimization directly using its native reasoning engine—zero runtime installation needed!

💻 Method C: Terminal CLI (For Scripts, CI/CD, or Standalone Use)

Execute token optimization and context telemetry directly from your terminal:

# View live context status & health dashboard
npx -y github:hanifalkauni/context-architect status

# Live monitoring mode with real-time refresh
npx -y github:hanifalkauni/context-architect monitor --live

# Audit repository token bloat and AST compression potential
npx -y github:hanifalkauni/context-architect audit ./src --html ./context-report.html

# Slice a large source code file into a lightweight structural AST skeleton
npx -y github:hanifalkauni/context-architect slice ./src/services/PaymentService.ts

# Focus AST slice on a specific symbol & its dependencies
npx -y github:hanifalkauni/context-architect slice ./src/services/PaymentService.ts --focus processPayment

# Compress test logs, stack traces, or git diffs
npx -y github:hanifalkauni/context-architect compress ./test-output.log

# Generate standalone visual HTML report
npx -y github:hanifalkauni/context-architect report --format html --out ./context-report.html

# (Optional) Inject IDE rule adapters into your project
npx -y github:hanifalkauni/context-architect init --ide cursor,windsurf,kiro --role coder

(Or use node ./bin/context-architect.js --mcp if developing locally)

🛠️ The 11 Native MCP Tools

🌐 Multi-IDE & Multi-Agent Compatibility

📊 Evaluation & Token Efficiency Benchmarks

🧪 Testing & Validation

Context-Architect includes a complete zero-dependency test suite covering all 11 MCP tools, slicers, memory tiers, and compressors:

npm test

🧪 Running Context-Architect Test Suite...

  ✅ PASS: Tokenizer & Model Database
  ✅ PASS: Pressure Gauge & Budget Allocator
  ✅ PASS: AST Engine - TypeScript Slicing
  ✅ PASS: AST Engine - Python Slicing
  ✅ PASS: AST Engine - Go Slicing
  ✅ PASS: Dependency Slicer & JIT Hydrator
  ✅ PASS: Log Collapser
  ✅ PASS: Diff Minimalizer
  ✅ PASS: Tree Condenser
  ✅ PASS: Tier 1 Hot Working Memory
  ✅ PASS: Tier 2 Warm Episodic Memory
  ✅ PASS: Tier 3 Cold Archival Store (BM25 Search)
  ✅ PASS: Semantic Garbage Collector
  ✅ PASS: KV-Cache Optimizer & Boundary Manager
  ✅ PASS: Checkpoint Manager & Subagent Sandbox & Symbol Guard
  ✅ PASS: Guardrails: Stream Interceptor, Secret Scrubber, Image Optimizer
  ✅ PASS: Attention Anchoring (Dual-Anchor) & Role Profiler
  ✅ PASS: Report Generator (HTML, Markdown, JSON)
  ✅ PASS: MCP Server - 11 Native Tools

========================================
🏁 Test Results: 19 passed, 0 failed
========================================

🤝 Contributing & Evaluation Hub

Contributions are warmly welcomed! Whether you want to add new language AST profiles, create new AI IDE adapters, optimize token compressors, or submit real-world benchmark evaluations:

1. Read our full Contributing Guide to understand the Zero External Dependencies and Sub-45ms Execution Speed architectural principles.

2. Submit real-world token optimization benchmarks and RFCs in the Evaluation & Feedback Hub using TEMPLATE_FEEDBACK.md.

3. Adding a new language profile: create profiles/<language>.profile.json, add test fixtures in tests/fixtures/, and verify with npm test.

4. Report issues, submit bug reports, or propose feature RFCs via GitHub Issues.

📜 License & Citation

Distributed under the MIT License. See LICENSE for full details.

SPDX-License-Identifier: MIT
Copyright (c) 2026 Hanif Al-Kauni

Built with ❤️ for the universal AI agent ecosystem.