AgentCache

Your codebase learns. AgentCache compiles what your AI agents discover into a SKILL.md that every future session — in any IDE, with any LLM — reads automatically.

npm install -g agentcache

That's it. No config. No accounts. No sync server.

The Problem

You tell Claude "don't mock the database in integration tests." It forgets. You tell Cursor the same thing. You tell Codex. You repeat yourself across every IDE, every session, every project.

Your agents are amnesiac. Your knowledge evaporates.

What AgentCache Does

After a few sessions, AgentCache produces a SKILL.md in your repo:

# Project Knowledge

## Rules
- Never mock the database in integration tests — we got burned when mocks passed but prod migration failed
- Always use snake_case for database columns
- Run type-check before committing

## Decisions
- Using Drizzle ORM over Prisma for raw SQL escape hatches
- PostgreSQL for all persistent state, Redis for ephemeral cache only

## Context
- Migrating from REST to GraphQL, both coexist until Q3
- Auth service rewrite driven by compliance (not tech debt)

This file lives at <repo>/.agentcache/skills/project-knowledge/SKILL.md. It's auto-discovered by 38+ tools that support the Agent Skills spec — no MCP connection required. Commit it. Every teammate gets your team's accumulated knowledge on clone.

The database is local. The output is git.

How It Works

Session 1 (Claude Code)     Session 2 (Cursor)     Session 3 (Codex)
       │                           │                       │
       └───────────────────────────┴───────────────────────┘
                                   │
                          AgentCache (MCP Server)
                                   │
                    ┌───────────────┴───────────────┐
                    │                               │
              ~/.agentcache/                  <repo>/.agentcache/
              agentcache.db                  skills/.../SKILL.md
              (local SQLite)                 (committed to git)

1. Session starts → agent calls inject_context → gets compiled rules, lessons, decisions
2. During session → agent calls compile_submit as it learns things
3. Session ends → knowledge compiles into the database
4. Periodically → database projects into SKILL.md for git distribution

Knowledge compounds. One lesson stated once propagates to every future session across every IDE.

Install

npm install -g agentcache

The install automatically:

1. Creates ~/.agentcache/agentcache.db
2. Detects your IDEs (Claude Code, Cursor, Roo Code, Windsurf, Continue, Codex)
3. Registers as an MCP server in each — with auto-approve
4. Sets up Claude Code hooks for transcript recovery
5. Compiles your existing transcript history in the background

Zero config. Zero setup. Start a session and it's working.

Supported IDEs

| IDE | MCP | Auto-Approve | Transcript Recovery | |-----|-----|-------------|-------------------| | Claude Code | ✓ | ✓ | Full (hooks + JSONL) | | Cursor | ✓ | ✓ | Full (agent transcripts) | | Roo Code (VS Code) | ✓ | ✓ | Full (task history) | | Codex | ✓ | ✓ | Full (session JSONL) | | Continue | ✓ | ✓ | Full (session JSON) | | Windsurf | ✓ | ✓ | Incremental only | | Goose | — | — | Full (SQLite) |

All IDEs share the same knowledge database. A rule learned in Claude Code is injected in Cursor the next time you open it.

Security Model

AgentCache creates a feedback loop: agents write observations → observations compile → knowledge injects into future sessions. This is the product's value and its attack surface.

Quarantine gate: Agent-submitted observations require confirmation across 2+ independent sessions before injection. A single prompt-injected compile_submit cannot poison your knowledge.

Human-only enforcement: Policy rules (that block tool calls) can only be created via CLI. No MCP tool can create policy.

Scope gate: Agent-submitted observations are always project-scoped. Global requires explicit human action.

Security Modes

{ "security": "auto" }

| Mode | Behavior | |------|----------| | auto | Quarantine — new items inject after 2+ session confirmations | | review | Nothing injects until agentcache review approves it | | locked | compile_submit disabled. Human-triggered batch only |

CLI

agentcache doctor                          # Diagnose installation
agentcache status                          # Knowledge stats
agentcache review                          # Approve/reject quarantined items
agentcache promote <id>                    # Approve a single item
agentcache add-rule "never force push" --enforce   # Create policy (human-only)
agentcache compile-all                     # Batch-compile all transcripts
agentcache setup                           # Re-register with IDEs

compile-all

Processes all uncompiled transcripts from all IDEs using the first available LLM backend:

1. CLI tools: claude, codex, gemini, copilot, aider, goose
2. Ollama at localhost:11434
3. ANTHROPIC_API_KEY or OPENAI_API_KEY

Runs automatically on install and when pending transcripts exceed 20.

Data

~/.agentcache/
├── agentcache.db          # Knowledge database (SQLite + WAL)
├── config.json            # Security mode
└── compile-all.lock       # Prevents concurrent compilation

<repo>/.agentcache/
└── skills/project-knowledge/SKILL.md   # Git-committed team knowledge

No network calls. No telemetry. No accounts. Everything stays on your machine (except what you choose to commit).

Principles

• Zero config — npm install -g is the only step
• Universal — MCP protocol, any IDE, any LLM
• Git-native output — SKILL.md is the distribution mechanism
• Secure by default — quarantine gate, scope restrictions, human-only policy
• Anti-bloat — 30-day decay, budget caps, confidence promotion

Contributing

git clone https://github.com/raghav-a21ai/agentcache
cd agentcache
npm install
npm run build
npm test   # 205 tests

License

MIT