agentcache 0.4.0 → 0.4.2

package/README.md

@@ -1,313 +1,163 @@
 # AgentCache
 
-**Knowledge cache for AI coding agents** — learns how you work, remembers across sessions, works everywhere.
-
-AgentCache observes your coding sessions and compiles reusable knowledge (rules, lessons, architectural decisions, context) into a local database. Every future session — regardless of IDE or LLM — gets the benefit of everything you've learned before.
-
-## Why
-
-Every AI coding session starts from zero. The agent doesn't know your team's conventions, past mistakes, or architectural decisions. You repeat yourself. Bugs recur. Context is lost.
-
-AgentCache fixes this. It's a persistent knowledge layer that:
-- **Learns** rules, lessons, and decisions from your sessions
-- **Injects** relevant knowledge at the start of every new session
-- **Works everywhere** — any IDE, any LLM, simultaneously
-- **Stays local** — SQLite database on your machine, nothing leaves your disk
-
-## Install
+**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.
 
 ```bash
 npm install -g agentcache
 ```
 
-Done. Start a new session in any IDE. AgentCache is already running.
-
-No `init`. No `setup`. No config. No second command. The install itself:
-1. Creates `~/.agentcache/agentcache.db` (your knowledge store)
-2. Detects installed IDEs (Claude Code, Cursor, Roo Code, Windsurf, Continue, Codex)
-3. Registers itself as an MCP server in each
-4. Sets up Claude Code hooks for automatic transcript recovery
-5. Spawns `compile-all` in background — compiles your entire transcript history from all IDEs immediately
-
-## How It Works
-
-```
-┌────────────────────────────────────────────────────────────────────────┐
-│                           Your Machine                                 │
-│                                                                        │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐                │
-│  │  Claude  │  │  Cursor  │  │   Roo    │  │  Codex   │  ...           │
-│  │   Code   │  │          │  │   Code   │  │          │                │
-│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘                │
-│       │             │             │             │                      │
-│       └─────────────┴─────────────┴─────────────┘                      │
-│                              │                                         │
-│                    MCP Protocol (stdio)                                │
-│                              │                                         │
-│                 ┌────────────┴────────────┐     ┌────────────────────┐ │
-│                 │  AgentCache MCP Server  │     │  agentcache        │ │
-│                 │   (agentcache serve)    │     │  compile-all       │ │
-│                 │                         │     │  (standalone CLI)  │ │
-│                 │  spawns compile-all ────┼────▶│                    │ │
-│                 │  when pending > 20      │     │  Uses: claude,     │ │
-│                 └────────────┬────────────┘     │  codex, gemini,    │ │
-│                              │                  │  ollama, API keys  │ │
-│                              │                  └─────────┬──────────┘ │
-│                              │                            │            │
-│                    ┌─────────┴────────────────────────────┘            │
-│                    │                                                   │
-│                    ▼                                                   │
-│           ┌────────────────────┐                                       │
-│           │ ~/.agentcache/     │                                       │
-│           │  agentcache.db     │                                       │
-│           │  compile-all.lock  │                                       │
-│           │  (SQLite + WAL)    │                                       │
-│           └────────────────────┘                                       │
-└────────────────────────────────────────────────────────────────────────┘
-```
+That's it. No config. No accounts. No sync server.
 
-### The Cycle
+---
 
-1. **Session starts** — agent calls `inject_context` → gets compiled rules, lessons, decisions
-2. **During session** — agent calls `compile_submit` incrementally as it learns things
-3. **Session ends** — knowledge is already saved. If agent didn't submit (abrupt exit), transcript recovery handles it next session.
+## The Problem
 
-### Knowledge Types
+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.
 
-| Type | Scope | Example |
-|------|-------|---------|
-| **Rule** | Global | "Always use snake_case for database columns" |
-| **Lesson** | Global | "Don't mock the database in integration tests — we got burned when mocked tests passed but prod migration failed" |
-| **Decision** | Project | "Using Drizzle ORM over Prisma because we need raw SQL escape hatches" |
-| **Context** | Project | "Currently migrating from REST to GraphQL, both coexist" |
+Your agents are amnesiac. Your knowledge evaporates.
 
-Rules and lessons are **global** — they apply to all your projects. Decisions and context are **project-specific**.
+## What AgentCache Does
 
-## MCP Tools
+After a few sessions, AgentCache produces a `SKILL.md` in your repo:
 
-AgentCache exposes 8 tools via the Model Context Protocol (prefixed as `mcp--agentcache--<tool>` in IDEs):
+```markdown
+# Project Knowledge
 
-| Tool | Purpose |
-|------|---------|
-| `inject_context` | Load compiled knowledge at session start |
-| `compile_submit` | Submit observations incrementally during session |
-| `compile_cluster` | Resolve clustering when observations overlap existing knowledge |
-| `compile_extract` | Process queued transcripts from previous sessions |
-| `enforce` | Check tool calls against enforced policy rules |
-| `save_observation` | Save a permanent observation (USER authority, never auto-deprecated) |
-| `get_knowledge` | Query the knowledge database |
-| `deprecate_knowledge` | Mark knowledge as deprecated when it's no longer valid |
+## 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
 
-## CLI Commands
+## Decisions
+- Using Drizzle ORM over Prisma for raw SQL escape hatches
+- PostgreSQL for all persistent state, Redis for ephemeral cache only
 
-```bash
-agentcache status          # Show knowledge stats for current project
-agentcache compile-all     # Batch-compile all unprocessed transcripts
-agentcache setup           # Re-register with IDEs (only if postinstall failed)
+## Context
+- Migrating from REST to GraphQL, both coexist until Q3
+- Auth service rewrite driven by compliance (not tech debt)
 ```
 
-### `compile-all` — Standalone Batch Compilation
+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.
 
-Processes all pending transcripts across every IDE without depending on MCP pipes or active sessions. Runs independently in a terminal.
+**The database is local. The output is git.**
 
-```bash
-agentcache compile-all
-```
+## How It Works
 
-**LLM backend detection** (first available wins):
-1. CLI tools with stored auth: `claude`, `codex`, `gemini`, `copilot`, `aider`, `goose`
-2. Ollama running locally (`localhost:11434`)
-3. `ANTHROPIC_API_KEY` environment variable
-4. `OPENAI_API_KEY` environment variable
+```
+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)
+```
 
-No API keys needed if you have any coding CLI installed — it uses their stored authentication.
+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
 
-**Automatic triggers:**
-- Runs as a background process after `npm install -g agentcache` (clears initial backlog)
-- Spawned by the MCP server when pending transcripts exceed 20 (ongoing janitor)
-- Lockfile (`~/.agentcache/compile-all.lock`) prevents concurrent runs
+Knowledge compounds. One lesson stated once propagates to every future session across every IDE.
 
-**Transcript sources:** Claude Code, Continue, Codex, Roo Code, Goose
+## Install
 
-Internal commands (called by hooks automatically, never by users):
 ```bash
-agentcache serve           # MCP server (IDEs spawn this)
-agentcache compile-session # Stop hook
-agentcache discover        # SessionStart hook
-agentcache enforce         # PreToolUse hook
+npm install -g agentcache
 ```
 
-## Design Principles
-
-### Zero Config
-
-`npm install -g agentcache` is the only step. It detects your IDEs, registers itself, and starts working. No dotfiles in your project. No init commands. No config to maintain.
-
-### Universal
-
-AgentCache uses MCP (Model Context Protocol) as its only interface. Any IDE that supports MCP works. Any LLM — Claude, GPT, Gemini, Qwen, Llama — can use the tools. No IDE-specific code paths. No LLM-specific logic.
-
-### Developer-Scoped
-
-One database per developer (`~/.agentcache/agentcache.db`), not per project. Rules and lessons learned in one project benefit all your projects. Project-specific decisions stay scoped to their project.
-
-### Resilient to Abrupt Exits
-
-Sessions can end without warning (crash, ctrl-c, network drop, MCP pipe death). AgentCache handles this through:
-- **Incremental submission** — observations are saved as they happen, not batched at the end
-- **Transcript recovery** — transcripts persist on disk across 5 IDEs (Claude Code, Continue, Codex, Roo Code, Goose) and are compiled by `compile-all`
-- **Pipe-independent compilation** — `compile-all` runs as a standalone process, not through MCP stdio pipes that can break during long operations
-- **Pending queue in SQLite** — concurrent access is safe, nothing lost to race conditions
-
-### Anti-Bloat
+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
 
-AgentCache prevents knowledge from growing unbounded:
-- **Confidence promotion** — observations need repeated confirmation before becoming high-confidence
-- **Decay** — auto-compiled items not seen in 30 days get archived
-- **Budget caps** — max 20 rules, 10 lessons, 10 decisions, 5 context items injected per session
-- **Priority ranking** — USER authority first, then by confidence and recency
+**Zero config. Zero setup. Start a session and it's working.**
 
 ## Supported IDEs
 
-| IDE | MCP | Auto-Approve | Transcript Recovery | Hooks |
-|-----|-----|-------------|--------------------|----|
-| Claude Code | Yes | Yes (automatic) | Full (JSONL) | Stop, SessionStart, PreToolUse |
-| Cursor | Yes | Yes (automatic) | Incremental only | — |
-| Roo Code | Yes | Yes (automatic) | Full (JSON via compile-all) | — |
-| Windsurf | Yes | Yes (automatic) | Incremental only | — |
-| Continue | Yes | Yes (automatic) | Full (JSON) | — |
-| Codex | Yes | Yes (automatic) | Full (JSONL via compile-all) | — |
-| Goose | — | — | Full (SQLite via compile-all) | — |
+| 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 are fully auto-approved at install time — no manual steps required.
+All IDEs share the same knowledge database. A rule learned in Claude Code is injected in Cursor the next time you open it.
 
-"Incremental only" means if the agent submits observations during the session, they're saved. If the session terminates before any submission, those observations are lost (no transcript access).
+## Security Model
 
-"via compile-all" means `agentcache compile-all` discovers and processes these transcripts in batch, independent of any active MCP session.
+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.
 
-## Skill Output (Agent Skills Spec)
+**Quarantine gate**: Agent-submitted observations require confirmation across 2+ independent sessions before injection. A single prompt-injected `compile_submit` cannot poison your knowledge.
 
-Compiled knowledge is automatically projected to SKILL.md files — the [Agent Skills open standard](https://agentskills.io) supported by 38+ tools (Claude Code, Cursor, Codex, Gemini CLI, Copilot, Roo Code, and more).
+**Human-only enforcement**: Policy rules (that block tool calls) can only be created via CLI. No MCP tool can create policy.
 
-```
-~/.agentcache/skills/developer-knowledge/SKILL.md    # Global: rules + lessons
-<repo>/.agentcache/skills/project-knowledge/SKILL.md  # Project: decisions + context
-```
-
-**Global skill** (`~/.agentcache/skills/`) — your developer identity. Rules and lessons learned across all projects. Auto-discovered by any Agent Skills-compatible tool without MCP.
-
-**Project skill** (`<repo>/.agentcache/skills/`) — project-specific decisions, context, and rules. Git-trackable. Team members get it on clone. **This is team knowledge sharing without a sync server — just git.**
-
-Skills auto-refresh on every compilation. Each file stays under 5,000 tokens (Agent Skills budget limit). High-confidence items appear first.
-
-Example output:
-```markdown
----
-name: project-knowledge
-description: "Project-specific decisions, rules, context, and lessons — compiled automatically from coding sessions by AgentCache"
----
+**Scope gate**: Agent-submitted observations are always project-scoped. Global requires explicit human action.
 
-## Rules
+### Security Modes
 
-Follow these without exception:
+```json
+{ "security": "auto" }
+```
 
-- Always use path aliases in imports
-- Never commit .env files [ENFORCED]
+| 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 |
 
-## Decisions
+## CLI
 
-Architectural choices in effect — do not contradict:
-
-- Using Drizzle ORM over Prisma for raw SQL escape hatches
-- PostgreSQL for all persistent state, Redis for ephemeral cache only
+```bash
+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
+```
 
-## Current Context
+## compile-all
 
-Active project state (may be temporal):
+Processes all uncompiled transcripts from all IDEs using the first available LLM backend:
 
-- Migrating from REST to GraphQL, both coexist until Q3
-```
+1. CLI tools: `claude`, `codex`, `gemini`, `copilot`, `aider`, `goose`
+2. Ollama at `localhost:11434`
+3. `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
 
-## Data Storage
+Runs automatically on install and when pending transcripts exceed 20.
 
-All data lives in `~/.agentcache/` (SQLite with WAL mode for concurrent access).
+## Data
 
 ```
 ~/.agentcache/
-├── agentcache.db                          # Knowledge, observations, sessions, pending queue
-├── compile-all.lock                       # Prevents concurrent compilation
-└── skills/developer-knowledge/SKILL.md    # Global skill (auto-generated)
-```
-
-No data leaves your machine. No network calls. No telemetry. No accounts.
+├── agentcache.db          # Knowledge database (SQLite + WAL)
+├── config.json            # Security mode
+└── compile-all.lock       # Prevents concurrent compilation
 
-## How Knowledge Compiles
-
-```
-Observations (raw)
-    │
-    ▼
-Extract → Normalize → Canonicalize → Cluster → Detect Contradictions → Compile
-    │                                                                      │
-    │  "Always use ESLint"                                                 │
-    │  "Always use ESLint"  ──→  deduplicated, confidence promoted         │
-    │  "Use Prettier not ESLint"  ──→  contradiction detected              │
-    │                                                                      ▼
-                                                            Knowledge Items (compiled)
-                                                            - status: active/deprecated/superseded
-                                                            - confidence: low/medium/high
-                                                            - authority: AUTO/USER
+<repo>/.agentcache/
+└── skills/project-knowledge/SKILL.md   # Git-committed team knowledge
 ```
 
-**Two compilation paths:**
-- **In-session** — the agent in your IDE processes extraction prompts via MCP tools (no separate LLM calls needed)
-- **Batch (`compile-all`)** — runs independently using any available LLM CLI or API, processes the full backlog without depending on active sessions
-
-**Two output formats:**
-- **MCP injection** — structured context served to agents at session start via `inject_context`
-- **SKILL.md files** — Agent Skills spec-compliant files auto-discovered by 38+ tools without MCP
-
-## Project Identity
-
-Projects are identified by a hash of their full filesystem path, not just the folder name. This means:
-- `/work/api` and `/personal/api` are different projects
-- Renaming a folder creates a new project identity
-- Knowledge doesn't leak between same-named projects
-
-## Roadmap
-
-### More IDEs & Coding Agents
-
-| Platform | Status |
-|----------|--------|
-| Claude Code | Supported |
-| Cursor | Supported |
-| Roo Code | Supported |
-| Windsurf | Supported |
-| Continue | Supported |
-| Codex | Supported |
-| Goose | Supported (transcript recovery via SQLite) |
-| Aider | Coming soon |
-| GitHub Copilot | Coming soon |
-| Zed AI | Coming soon |
-
-Any tool that supports MCP can use AgentCache today via `agentcache serve`. Native integrations for the above are planned to ensure zero-config setup.
-
-### Native Plugins
-
-Marketplace listings and deeper UI integrations for all supported IDEs — surfacing knowledge inline, showing compilation status, and providing one-click management of rules and decisions.
-
-### Team Knowledge Sharing
-
-Share compiled knowledge across your team. Rules and lessons that work for one developer benefit everyone.
-
-### Cloud Sync
-
-Sync your knowledge database across machines. Same developer, different computers, same knowledge.
+No network calls. No telemetry. No accounts. Everything stays on your machine (except what you choose to commit).
 
-### Analytics Dashboard
+## Principles
 
-Visibility into what AgentCache is learning — compilation stats, knowledge growth, most-referenced rules, and session coverage.
+- **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
 
@@ -316,7 +166,7 @@ git clone https://github.com/raghav-a21ai/agentcache
 cd agentcache
 npm install
 npm run build
-npm test
+npm test   # 205 tests
 ```
 
 ## License

package/dist/chunk-5UO7NJPQ.js

@@ -0,0 +1,71 @@
+// src/utils/ide-detector.ts
+import { existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+function getRooConfigPath() {
+  const home = homedir();
+  if (process.platform === "darwin") {
+    return join(home, "Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json");
+  }
+  if (process.platform === "win32") {
+    return join(process.env.APPDATA || join(home, "AppData/Roaming"), "Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json");
+  }
+  return join(home, ".config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json");
+}
+function getWindsurfConfigPath() {
+  const home = homedir();
+  return join(home, ".codeium", "windsurf", "mcp_config.json");
+}
+function getContinueConfigPath() {
+  const home = homedir();
+  return join(home, ".continue", "mcpServers", "agentcache.json");
+}
+function getCodexConfigPath() {
+  const home = homedir();
+  return join(home, ".codex", "config.toml");
+}
+function detectInstalledIdes() {
+  const home = homedir();
+  return [
+    {
+      name: "Claude Code",
+      detected: existsSync(join(home, ".claude")),
+      mcpConfigPath: join(home, ".claude.json"),
+      mcpConfigFormat: "claude-settings"
+    },
+    {
+      name: "Cursor",
+      detected: existsSync(join(home, ".cursor")),
+      mcpConfigPath: join(home, ".cursor", "mcp.json"),
+      mcpConfigFormat: "mcp-json"
+    },
+    {
+      name: "Roo Code",
+      detected: existsSync(getRooConfigPath()),
+      mcpConfigPath: getRooConfigPath(),
+      mcpConfigFormat: "mcp-json"
+    },
+    {
+      name: "Windsurf",
+      detected: existsSync(join(home, ".codeium", "windsurf")) || existsSync(join(home, ".windsurf")),
+      mcpConfigPath: getWindsurfConfigPath(),
+      mcpConfigFormat: "mcp-json"
+    },
+    {
+      name: "Continue",
+      detected: existsSync(join(home, ".continue")),
+      mcpConfigPath: getContinueConfigPath(),
+      mcpConfigFormat: "continue-dir"
+    },
+    {
+      name: "Codex",
+      detected: existsSync(join(home, ".codex")),
+      mcpConfigPath: getCodexConfigPath(),
+      mcpConfigFormat: "codex-toml"
+    }
+  ];
+}
+
+export {
+  detectInstalledIdes
+};

package/dist/{chunk-ESDTP63R.js → chunk-PSASDZQE.js}

@@ -277,16 +277,17 @@ var SqliteKnowledgeRepository = class {
     if (!row) return null;
     return this.mapKnowledgeItem(row);
   }
-  getKnowledgeForContext(project) {
+  getKnowledgeForContext(project, opts) {
     const decayThreshold = Date.now() - 30 * 24 * 60 * 60 * 1e3;
     this.db.prepare(
       `UPDATE knowledge_items SET status = 'archived', updated_at = ?
        WHERE status = 'active' AND authority = 'AUTO' AND last_seen_at < ?`
     ).run(Date.now(), decayThreshold);
+    const authorityFilter = opts?.userOnly ? `AND authority = 'USER'` : `AND (authority = 'USER' OR observation_count >= 2)`;
     const rows = this.db.prepare(
       `SELECT * FROM knowledge_items WHERE status = 'active'
          AND (scope = 'global' OR project = ?)
-         AND (authority = 'USER' OR observation_count >= 2)
+         ${authorityFilter}
          ORDER BY
            CASE authority WHEN 'USER' THEN 0 ELSE 1 END,
            CASE confidence WHEN 'high' THEN 3 WHEN 'medium' THEN 2 ELSE 1 END DESC,
@@ -382,6 +383,11 @@ var SqliteKnowledgeRepository = class {
     const row = this.db.prepare("SELECT COUNT(*) as count FROM pending_transcripts").get();
     return row.count;
   }
+  grandfatherExistingItems() {
+    this.db.prepare(
+      `UPDATE knowledge_items SET observation_count = 2 WHERE authority = 'AUTO' AND observation_count < 2 AND status = 'active'`
+    ).run();
+  }
   getQuarantinedItems(project) {
     const sql = project ? `SELECT * FROM knowledge_items WHERE status = 'active' AND authority = 'AUTO' AND observation_count < 2 AND (scope = 'global' OR project = ?) ORDER BY created_at DESC` : `SELECT * FROM knowledge_items WHERE status = 'active' AND authority = 'AUTO' AND observation_count < 2 ORDER BY created_at DESC`;
     const rows = project ? this.db.prepare(sql).all(project) : this.db.prepare(sql).all();