🧠 AI Context Stack - Reduce Claude Code Tokens by 80-90%

Automatic context injection for Claude Code to dramatically reduce token usage

Anthropic recently cut token limits for Claude Code users. This tool helps you get your quota back by automatically injecting stored context instead of sending it every time.

🎯 The Problem

Every Claude Code conversation sends the same context repeatedly:

Without AI Context Stack:
├── Project structure: 800 tokens
├── Dependencies: 600 tokens
├── Coding standards: 400 tokens
├── Architecture: 700 tokens
├── API docs: 500 tokens
└── Previous decisions: 400 tokens
    TOTAL: 3,400 tokens EVERY conversation

Daily usage (10 conversations):
34,000 tokens wasted on repeated context

Monthly: 1,020,000 tokens (exceeds most plans!)

✨ The Solution

Store context once, reference it automatically:

With AI Context Stack:
├── First conversation: Store context (3,400 tokens one-time)
└── Every other conversation: Reference stored context (100 tokens)
    SAVINGS: 3,300 tokens per conversation (97%)

Daily savings: 33,000 tokens
Monthly savings: 990,000 tokens

It's like getting 2-3x your plan back!

💰 Cost & Requirements

Current Version (v1.0 - Proxy Mode)

What You Need:

✅ Claude Code subscription ($20/month)
✅ Anthropic API key (pay-per-use)
✅ Docker & Docker Compose

Why Two Payments? The current version uses a proxy architecture that intercepts Claude Code's API calls and forwards them to Anthropic. This means you're using the public Anthropic API, which requires an API key.

Cost Breakdown:

Claude Code Subscription: $20/month (fixed)
+ Anthropic API Usage:    ~$0.15-1.00/month (with this tool)
─────────────────────────────────────────────────
TOTAL:                    ~$20.15-21.00/month

The Good News:

Even with dual payment, token savings make it worthwhile
API costs are minimal compared to hitting Claude Code limits
Coming Soon: Native MCP version (no API key needed!)

Future Version (v2.0 - Native MCP) 🚧

What You'll Need:

✅ Claude Code subscription only ($20/month)
❌ No Anthropic API key needed
❌ No additional costs

We're actively working on a native MCP server implementation that integrates directly with Claude Code, eliminating the need for the proxy and API key entirely.

Timeline: Aiming for v2.0 release within 2-3 weeks.

🚀 Quick Start

Prerequisites

Docker & Docker Compose
Anthropic API key (for current version)
5 minutes

Installation

# 1. Clone the repository
git clone https://github.com/aandersen2323/ai-context-stack.git
cd ai-context-stack

# 2. Run setup (installs everything)
./setup-claude-code.sh

# 3. Follow the prompts to add your API key

That's it! The system is now running.

💡 How It Works

┌─────────────────────────────────────┐
│  Your Claude Code                   │
│  (configured to use proxy)          │
└──────────────┬──────────────────────┘
               │ API Request
               ▼
┌─────────────────────────────────────┐
│  Token Proxy (port 8088)            │
│  1. Receives your request           │
│  2. Searches Memory MCP for context │
│  3. Injects relevant context        │
│  4. Forwards to Anthropic           │
└──────────────┬──────────────────────┘
               │
               ├──► Memory MCP (port 8015)
               │    Stores your project context
               │
               └──► Anthropic API
                    Gets request WITH context

Result: You save 80-90% tokens!

📋 Usage Guide

1. Auto-Discover Your Project Context (Recommended!)

The easiest way to get started - let the tool automatically scan your project:

# Run auto-discovery from your project directory
./scripts/auto-discover.sh /path/to/your/project

# Or from within your project:
cd /path/to/your/project
/path/to/ai-context-stack/scripts/auto-discover.sh .

What it discovers:

✅ package.json → Project name, framework, dependencies, scripts
✅ README.md → Project documentation
✅ tsconfig.json → TypeScript configuration
✅ .eslintrc.* → Code quality standards
✅ .env.example → Required environment variables
✅ docker-compose.yml → Architecture and services
✅ vite.config.* / webpack.config.js → Build tools
✅ Project structure → Folder organization patterns

Example output:

╔══════════════════════════════════════════════════════════════╗
║  AI Context Stack - Auto-Discovery                          ║
╚══════════════════════════════════════════════════════════════╝

📂 Scanning project: /my-react-app

🔍 Analyzing package.json...
  💾 Storing: package.json
     Tags: project,react,javascript
     ✅ Stored

🔍 Analyzing README.md...
  💾 Storing: README.md
     Tags: project,documentation,readme
     ✅ Stored

✅ Auto-Discovery Complete!
📊 Discovered and stored: 8 context items

2. Manual Context Storage (Advanced)

For specific context not auto-discovered, store it manually:

# Project information
./scripts/store-context.sh \
  "Project: Building a React e-commerce app with TypeScript" \
  "project,react,typescript"

# Coding standards
./scripts/store-context.sh \
  "Use snake_case for Python, camelCase for JavaScript" \
  "standards,python,javascript"

# Architecture decisions
./scripts/store-context.sh \
  "API base URL: https://api.example.com, use JWT auth" \
  "api,config,architecture"

# Dependencies
./scripts/store-context.sh \
  "Using React 18, TypeScript 5, Vite, TailwindCSS" \
  "dependencies,react"

3. View Stored Context

./scripts/list-context.sh

Output:

📋 Stored Context:
==================
Total items: 4

📌 [project, react, typescript] Project: Building a React e-commerce app...
   Handle: mem_1234567890_abc
   Time: 2025-10-09T22:00:00Z

📌 [standards, python, javascript] Use snake_case for Python...
   Handle: mem_1234567891_def
   Time: 2025-10-09T22:01:00Z

4. Configure Claude Code

Option A: Using Claude Code directly

Edit your Claude Code configuration to point to the proxy:

{
  "apiEndpoint": "http://localhost:8088"
}

Option B: Environment variable

export ANTHROPIC_BASE_URL=http://localhost:8088

5. Use Claude Code Normally

Just use Claude Code as you normally would! The proxy automatically:

Detects relevant context based on your conversation
Injects it into your request
Sends to Anthropic with full context
Saves you 80-90% tokens!

🧪 Test the System

# Test the proxy is working
./scripts/test-proxy.sh

Expected output:

🧪 Testing Token Proxy...
========================

📤 Sending test request to proxy...
✅ Success!

Response: Hello! I'm Claude, happy to help you today.

📊 Token Usage:
   Input:  25 tokens
   Output: 12 tokens

📊 Real-World Example

Without AI Context Stack

Session 1: "Build a login page"
- Send project context: 500 tokens
- Send dependencies: 300 tokens
- Send standards: 200 tokens
- Your question: 50 tokens
TOTAL: 1,050 tokens

Session 2: "Add password reset"
- Send project context: 500 tokens
- Send dependencies: 300 tokens
- Send standards: 200 tokens
- Your question: 50 tokens
TOTAL: 1,050 tokens

10 sessions: 10,500 tokens

With AI Context Stack

Session 1: "Build a login page"
- Store project context: 500 tokens (one-time)
- Store dependencies: 300 tokens (one-time)
- Store standards: 200 tokens (one-time)
- Your question: 50 tokens
TOTAL: 1,050 tokens

Session 2: "Add password reset"
- Reference stored context: 50 tokens (automatic!)
- Your question: 50 tokens
TOTAL: 100 tokens

10 sessions: 1,950 tokens
SAVINGS: 8,550 tokens (81%)

🎯 What to Store

✅ Good Things to Store

Project information: Name, purpose, tech stack
Dependencies: Frameworks, libraries, versions
Coding standards: Style guides, naming conventions
Architecture: Patterns, folder structure
API endpoints: Base URLs, authentication
Previous decisions: Why you chose X over Y
Common tasks: How to run tests, deploy, etc.

❌ Don't Store

Secrets (API keys, passwords) - use environment variables
Temporary information that changes often
User-specific data (privacy concerns)
Very short context (overhead > benefit)

🛠️ Commands Reference

# Start services
docker compose up -d

# Stop services
docker compose down

# View logs
docker compose logs -f

# View memory logs only
docker compose logs -f memory-mcp

# View proxy logs only
docker compose logs -f token-proxy

# Auto-discover project context
./scripts/auto-discover.sh /path/to/project

# Store context manually
./scripts/store-context.sh "text" "tag1,tag2"

# List all context
./scripts/list-context.sh

# Test proxy
./scripts/test-proxy.sh

# Restart services
docker compose restart

📈 Monitoring Token Savings

Method 1: Analytics Dashboard (NEW! ✨)

The easiest way to visualize your savings!

Access the real-time dashboard at: http://localhost:8088/dashboard

What you'll see:

📊 Total tokens saved across all requests
📉 Average reduction percentage (typically 80-90%)
🎯 Context hit rate (how often context is found)
📈 Hourly savings chart (last 24 hours)
🕐 Recent requests table with detailed metrics
🧠 Patterns learned by auto-learning system

Features:

✅ Auto-refreshes every 5 seconds
✅ Shows last 1,000 requests
✅ Tracks hourly trends
✅ No configuration needed

Quick Access:

# Open dashboard in your browser
open http://localhost:8088/dashboard

# Or get raw stats via API
curl http://localhost:8088/api/dashboard | jq

📖 Full Documentation: See ANALYTICS_DASHBOARD.md

Method 2: Log Monitoring

The proxy also logs every request showing token savings:

docker compose logs -f token-proxy

Look for lines like:

[Proxy] Searching memory with tags: react, project
[Proxy] Found 3 context items (~800 tokens)
[Proxy] 🎉 Estimated tokens saved: 800 (context auto-injected)

🔧 Configuration

Environment Variables

Edit .env file:

# Required
ANTHROPIC_API_KEY=sk-ant-your-key-here

# Optional
PORT=8088                                  # Proxy port
MEMORY_MCP_URL=http://localhost:8015       # Memory MCP URL
MEMORY_FILE_PATH=./memory.json             # Where to store memory

Auto-Tagging

The proxy automatically detects context based on keywords:

"python" → searches for python tag
"react" → searches for react tag
"api" → searches for api tag
"project" → searches for project tag
"architecture" → searches for architecture tag

You can customize this in token-proxy/src/index.ts.

🐛 Troubleshooting

Services won't start

# Check if ports are in use
lsof -i :8088
lsof -i :8015

# Check logs
docker compose logs

Context not being injected

# Verify memory has items
./scripts/list-context.sh

# Check proxy logs for "Found N context items"
docker compose logs token-proxy | grep "Found"

# Test proxy directly
./scripts/test-proxy.sh

High token usage still

Make sure you:

Stored relevant context with good tags
Configured Claude Code to use proxy
Tags in context match your conversation topics

🎓 Advanced Usage

Custom Tags

# Store with multiple specific tags
./scripts/store-context.sh \
  "Database: PostgreSQL on localhost:5432, user: dev" \
  "database,postgresql,config,dev"

# Store with TTL (auto-delete after 30 days)
curl -X POST http://localhost:8015/tools/memory.pin \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Temporary: API endpoint moved to /v2/",
    "tags": ["api", "temp"],
    "ttl": 30
  }'

Search Context

# Search by tag
curl -X POST http://localhost:8015/tools/memory.search \
  -H "Content-Type: application/json" \
  -d '{"tags": ["react"]}' | jq

Delete Context

# Get handle from list-context.sh, then:
curl -X POST http://localhost:8015/tools/memory.unpin \
  -H "Content-Type: application/json" \
  -d '{"handle": "mem_1234567890_abc"}'

📊 Architecture

ai-context-stack/
├── token-proxy/           # Intercepts Claude API calls
│   ├── src/
│   │   └── index.ts      # Main proxy server
│   ├── Dockerfile
│   └── package.json
│
├── memory-mcp/           # Stores context with tagging
│   ├── src/
│   │   └── index.ts      # HTTP API wrapper for memory
│   ├── Dockerfile
│   └── package.json
│
├── scripts/              # Helper scripts
│   ├── store-context.sh  # Store new context
│   ├── list-context.sh   # List all context
│   └── test-proxy.sh     # Test the system
│
├── docker-compose.yml    # Orchestrates everything
├── setup-claude-code.sh  # One-command setup
└── README.md             # This file

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Test with ./scripts/test-proxy.sh
Submit a pull request

📄 License

MIT License - see LICENSE

🙏 Credits

Built with:

Model Context Protocol by Anthropic
Express.js for HTTP servers
Docker for easy deployment

💬 Support

🐛 Issues: https://github.com/aandersen2323/ai-context-stack/issues
💡 Discussions: https://github.com/aandersen2323/ai-context-stack/discussions

⚡ Quick Reference

# Setup (first time)
./setup-claude-code.sh

# Auto-discover your project
./scripts/auto-discover.sh .

# Store additional context manually
./scripts/store-context.sh "Your context" "tag1,tag2"

# View all stored context
./scripts/list-context.sh

# Test it works
./scripts/test-proxy.sh

# View logs
docker compose logs -f token-proxy

# Stop
docker compose down

🎉 Start saving tokens today!

Configure Claude Code to use http://localhost:8088 and watch your token usage drop by 80-90%.

Questions? Open an issue on GitHub!

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github/workflows		.github/workflows
examples		examples
memory-mcp		memory-mcp
scripts		scripts
token-proxy		token-proxy
.env.example		.env.example
.gitignore		.gitignore
ANALYTICS_DASHBOARD.md		ANALYTICS_DASHBOARD.md
CHANGELOG.md		CHANGELOG.md
CONVERSATION_LEARNING.md		CONVERSATION_LEARNING.md
DEMO_RESULTS.md		DEMO_RESULTS.md
HIERARCHICAL_CONTEXT.md		HIERARCHICAL_CONTEXT.md
README.md		README.md
docker-compose.yml		docker-compose.yml
setup-claude-code.sh		setup-claude-code.sh

aandersen2323/ai-context-stack

Folders and files

Latest commit

History

Repository files navigation