README.md

May 7, 2026 · View on GitHub

🧠 Kahuna

Your AI copilot's memory. Persistent context across sessions, projects, and teams.

Give your coding agent the context it needs — automatically.

Works with Claude Code · more copilots coming soon

The Problem

Every time you start a new conversation with your AI copilot, it forgets everything.

🔄 You repeat the same context about your project, your team, your standards
🤷 The copilot makes mistakes you've already corrected in past sessions
📄 Your policies, specs, and business rules sit in files the copilot never sees
🧠 Decisions and rationale from past conversations are lost forever

Copilots are powerful — but they have amnesia.

The Solution

Kahuna gives your copilot a persistent memory that grows smarter over time.

Without Kahuna	With Kahuna
Copilot starts fresh every session	Copilot remembers what it learned
You repeat context manually	Context surfaces automatically
Knowledge lives in your head	Knowledge lives in a structured KB
Decisions are forgotten	Decisions persist across sessions

How it works: Kahuna runs as an MCP server alongside your copilot. You teach it your context once — policies, specs, decisions, patterns — and it proactively surfaces the right knowledge for each task.

🔒 All data stays local. Your code and context never leave your machine.

Quickstart (Claude Code)

Step 1: Add Kahuna to Claude Code

claude mcp add kahuna -s user -e ANTHROPIC_API_KEY="your-anthropic-api-key" -- npx @aurite-ai/kahuna

Scope options:

-s project — Config stored for current project only

-s user — Config stored globally (available across all projects)

Step 2: In any project, tell your copilot:

"Set up Kahuna"

This deploys copilot rules and runs onboarding. The copilot asks a few questions to understand your context — this only happens once.

Step 3: Start teaching it your context:

"learn ~/Downloads/api-guidelines.pdf"

"learn the docs/ folder"

Step 4: Start working — Kahuna surfaces the right context automatically.

"build a customer support agent"

Kahuna feeds your copilot your API conventions, auth patterns, and related context. No reminders needed.

📦 More installation options (npm global, Docker, from source)

npm (Global Install)

npm install -g @aurite-ai/kahuna

Configure your MCP client to use kahuna-mcp as the command.

npx (No Install)

npx @aurite-ai/kahuna

Docker

docker pull kahuna/mcp
docker run -i kahuna/mcp

From Source

git clone https://github.com/Aurite-ai/kahuna.git
cd kahuna
pnpm install
pnpm --filter @aurite-ai/kahuna build
pnpm --filter @aurite-ai/kahuna bundle

What It Looks Like

You teach Kahuna your company's context:

"learn ~/docs/api-guidelines.pdf"

"learn the docs/ folder"

Later, you start a task:

"build a customer support agent"

Kahuna automatically surfaces the relevant context to your copilot:

✅ Your API conventions and auth patterns
✅ Customer data models and access policies
✅ Error handling and response format standards
✅ Related endpoints already in the codebase

Your copilot builds it right the first time — no reminders needed.

How It Works

┌─────────────────────────────────────────────────────────────────┐
│  YOU                          COPILOT                  KAHUNA   │
│                                                                 │
│  "set up Kahuna"  ─────────►  deploys rules  ─────►  .claude/   │
│                               asks questions          stores    │
│                                                       context   │
│                                                                 │
│  "learn these docs" ───────►  kahuna_learn   ─────►  knowledge  │
│                                                       base      │
│                                                                 │
│  "build feature X" ────────►  kahuna_prepare ─────►  surfaces   │
│                               _context                relevant  │
│                                                       files     │
└─────────────────────────────────────────────────────────────────┘

💡 If Kahuna saves you from repeating yourself, consider giving it a ⭐. It helps others discover the project.

The Problem
The Solution
Quickstart
What It Looks Like
How It Works
How It Compares
Features
Available Tools
Documentation
Contributing
License

How It Compares

Feature	Kahuna	Copilot Memory	RAG Tools	Manual Context
Persists across sessions	✅	Partial	✅	❌
Learns from files & conversations	✅	❌	Files only	N/A
Proactive context surfacing	✅	❌	Query-based	❌
Auto-classifies knowledge	✅	❌	❌	Manual
Works across projects	✅	❌	Varies	❌
Zero-config for copilot	✅	✅	❌	❌
Data stays local	✅	❌	Varies	✅

Kahuna is not a replacement for built-in copilot memory — it's what copilot memory should have been.

Features

🧠 Knowledge Base — Store, categorize, and retrieve context from markdown files
🎯 Smart Context Surfacing — Automatically surface relevant knowledge for your task
🔗 Integration Management — Discover, verify, and use external service integrations
🔐 Secure Credential Vault — Store and manage secrets with multiple provider support
📊 Usage Tracking — Monitor token consumption and costs per project
🚀 Onboarding System — Guided setup for organization and project context

Available Tools

Tool	Description
`kahuna_initialize`	Deploys copilot rules, runs onboarding
`kahuna_learn`	Adds files to knowledge base with classification
`kahuna_prepare_context`	Surfaces relevant knowledge for a task
`kahuna_ask`	Quick Q&A against the knowledge base
`kahuna_delete`	Remove outdated files from the knowledge base
`kahuna_provide_context`	Store org or user context in the knowledge base
`kahuna_usage`	View token usage and cost summary for the project
`kahuna_list_integrations`	List all discovered integrations and their status
`kahuna_use_integration`	Execute operations on discovered integrations
`kahuna_verify_integration`	Verify integration credentials and connectivity
`health_check`	Verify MCP server connectivity

Documentation

For Users:

MCP Server Documentation — Installation, tools, configuration
Advanced Documentation — Integrations, vault, KB structure

For Contributors:

Product Design — Core concepts, tool specifications
Architecture: Repository Infrastructure
Architecture: Context Management System

Contributing

We welcome contributions of all kinds!

🐛 Found a bug? Open an issue
💡 Have an idea? Open a feature request
🔧 Want to contribute code? Open a PR

🛠️ Developer Setup

Prerequisites

Node.js 18+
pnpm 9+

Quick Start

# Install dependencies
pnpm install

# Set up environment
cp apps/mcp/.env.example apps/mcp/.env

# Build workspace packages
pnpm build

# Run tests
pnpm test

Scripts

Command	Description
`pnpm build`	Build all packages (via Turborepo)
`pnpm test`	Run all tests across workspace
`pnpm lint`	Lint codebase (Biome)
`pnpm lint:fix`	Lint and auto-fix issues
`pnpm format`	Format codebase (Biome)
`pnpm typecheck`	Type-check all packages
`pnpm clean`	Remove build artifacts and caches

Testing CLI

Command	Description
`pnpm kahuna-test`	Run testing CLI
`pnpm test:create`	Create a test project from a scenario
`pnpm test:list`	List available scenarios and test projects
`pnpm test:collect`	Collect results from a test session

Project Structure

kahuna/
├── apps/
│   └── mcp/                # MCP server (stdio) — context management tools
│       ├── src/
│       │   ├── knowledge/  # Knowledge base domain logic (agents, storage, surfacing)
│       │   ├── integrations/   # External service integration management
│       │   ├── vault/      # Secure credential management
│       │   ├── usage/      # Token usage and cost tracking
│       │   └── tools/      # MCP tool handlers
│       └── templates/      # Project initialization templates
├── packages/
│   ├── testing/            # QA testing infrastructure (scenarios + CLI)
│   └── vck-templates/      # Copilot configuration templates
└── docs/                   # Documentation

License

MIT