Grape

Better context transport for AI coding agents.

Documentation · Architecture · Roadmap · Contributing

Stop making agents rediscover the same repo context every chat.

AI coding agents are powerful, and they can already read files in the current repo. That is not the hard part.

The hard part is read amplification. Agents reread the same files, rules, decisions, and failure context across chats, tools, clients, and long-running tasks.

They reread the same files. They rediscover the same project rules. They forget what changed between turns. They keep stale assumptions after branch switches and file edits. They burn tool calls rebuilding context they already had.

Grape is not a repo reader. It is a repo-backed context continuity and guardrail layer for coding agents.

It compiles the useful parts of your repo into dependency-tracked context artifacts, remembers what a specific agent session has already seen, and sends only what is new, changed, pinned, restorable, or stale.

The value is not the first read. The value is avoiding repeated rereads and stale assumptions after the first turn.

What Grape does

Grape sits between your repository and your AI coding agent.

MCP clients can read files, but they do not automatically preserve task-safe context across chats, tools, clients, and handoffs. Grape gives those clients a stable local surface for session ledgers, restore tokens, invalidation warnings, and proof-backed excerpts.

It helps the agent answer three questions every turn:

1. What context does this task need?
2. What context has this session already received?
3. What previous context is now stale because the repo changed?

Instead of shipping a fresh wall of files every time, Grape returns a structured context pack:

Item	Meaning
NEW	Context the current session has not seen yet.
CHANGED	Context that changed since the session last saw it.
PINNED	Safety-critical context that must be resent.
OMIT_UNCHANGED	Context safely omitted because this same session already received it.
RESTORE_AVAILABLE	Omitted context that can be fetched back if needed.
INVALIDATE_PREVIOUS	Prior context that should no longer be trusted.

Grape is not trying to replace your coding agent. It makes your existing agent better at carrying repository context across turns.

Install

Requirements:

• Node.js 22.13 or newer
• npm
• Git

Install Grape:

npm install -g grape-context

Verify the install:

grape --version
grape help
grape init --dry-run

Quick start

1. Install: npm install -g grape-context
2. Initialize: grape init --connect (from your repository root)
3. Connect MCP: grape mcp --install --client cursor, grape mcp --install --client claude, grape mcp --install --client codex, or grape mcp --install --client generic
4. Agent loop: the agent calls grape_get_context each turn with a stable sessionId and stable task text

Full walkthrough: Getting started.

Initialize it inside a repository:

grape init --connect

This creates local Grape state, captures the initial repository snapshot, and prints MCP setup guidance for your coding agent.

Check local privacy settings:

grape doctor
grape doctor --privacy

Use it with an agent

Grape works best through MCP.

For Cursor, write the project-local MCP config:

grape mcp --install --client cursor

This writes or merges .cursor/mcp.json.

For Claude Desktop, write the global Claude Desktop MCP config when Grape can resolve the platform path safely:

grape mcp --install --client claude

This writes or merges claude_desktop_config.json.

For Codex, write the project-local Codex MCP config:

grape mcp --install --client codex

This writes or merges .codex/config.toml for trusted Codex projects. It preserves unrelated TOML and refuses to replace an existing [mcp_servers.grape] table unless you pass --force.

For a generic JSON MCP client, print the config or merge an explicit config file:

grape mcp --install --client generic
grape mcp --install --client generic --config-path ./mcp.json

Generic has no default write path. Without --config-path, it prints the JSON and writes nothing.

Preview any change without writing:

grape mcp --install --client cursor --dry-run
grape mcp --install --client claude --dry-run
grape mcp --install --client codex --dry-run
grape mcp --install --client generic --dry-run

Use --config-path <path> to override the target config file. If an existing Grape MCP entry differs, Grape refuses to replace it unless you pass --force. Unrelated MCP servers are preserved.

To add project guidance for agents, print a path-neutral AGENTS.md snippet:

grape mcp --print-agents-snippet

Review the snippet before adding it to your repository rules. Grape does not edit AGENTS.md automatically.

Grape also ships a repo-local Codex plugin in plugins/grape with a marketplace file at .agents/plugins/marketplace.json:

codex plugin marketplace add .
codex plugin add grape@grape-local

Run those commands from the repository root. The plugin exposes grape mcp --stdio and a Grape skill for Codex. It assumes the grape command is on PATH. Use grape mcp --install --client codex when you need project-local .codex/config.toml with an exact working directory. The plugin does not ship hooks.

To verify the local Codex path without touching your normal Codex config:

npm run build
npm run codex:check

For older builds that do not recognize grape mcp --install, use the manual config fallback:

grape mcp --print-config

Paste the printed JSON into your MCP client config. Auto-install and manual config both launch:

grape mcp --stdio --repo <repo-root>

Use the repository root for both cwd and --repo. MCP stdio messages are newline-delimited JSON-RPC objects. Do not use Content-Length header framing.

The auto-install commands are separate from MCP stdio framing. Client configs launch grape mcp --stdio --repo <repo-root> and expect newline-delimited JSON-RPC over stdio.

After setup, your MCP-capable coding agent calls:

grape_get_context

The agent can then request task-specific repository context without manually rebuilding the same prompt every turn.

Copy-ready agent instruction:

At the start of each repo task turn, call grape_get_context with a stable sessionId and the current task. Treat INVALIDATE_PREVIOUS entries as stale and unsafe. If context is omitted, restore it by token only when needed. For security, auth, payments, data deletion, or deployment tasks, rely on exact proof-backed excerpts rather than summaries.

If the client does not connect:

• run grape --version in the same environment the client uses
• for Cursor, check .cursor/mcp.json
• for Claude Desktop, check claude_desktop_config.json
• confirm cwd and --repo point at the same repository root
• confirm no wrapper script prints banners or logs to stdout
• run grape doctor and grape doctor --privacy

A typical loop looks like this:

User asks coding agent to fix a task
Agent calls grape_get_context
Grape returns relevant repo context
Agent edits code
Repo changes
Agent calls grape_get_context again
Grape sends only the useful delta and invalidates stale context

What happens on the second turn

On the first turn, Grape sends the context needed for the task and records what the agent saw.

On later turns in the same session, Grape sends only what is new, changed, pinned, stale, or restorable. If a file, rule, dependency, branch, or worktree state changes, Grape tells the agent which previous context must stop being trusted.

That is Grape's main difference from repo graph tools. Graph tools help agents find repo structure. Grape helps agents carry repo context safely across turns.

Second-turn behavior:

• OMIT_UNCHANGED means this exact session already received unchanged, safe-to-omit context.
• RESTORE_AVAILABLE gives the agent a token to fetch omitted context only if needed.
• INVALIDATE_PREVIOUS tells the agent a prior context item is stale and unsafe to keep using.
• PINNED context is resent when safety policy requires it.
• high-risk tasks such as security, auth, payments, data deletion, or deployment require exact source, config, or rule evidence instead of summaries.

Manual CLI usage is available for debugging and fallback:

grape sync
grape compact
grape export
grape purge
grape compile --task "Explain the files I need to edit"
grape diff-context --task "Explain the files I need to edit"
grape status
grape doctor
grape sessions
grape artifacts
grape run --session <id> -- npm test
grape omitted --session <id>
grape stale
grape conflicts
grape bench --fixture <name>
grape mcp --print-config

Use grape sessions after repeated MCP or CLI turns to see local continuity evidence: what was sent, what was omitted with restore handles, and what stale context was invalidated.

See Getting started, the full CLI reference, and MCP tools.

How Grape differs from graph and memory tools

Grape is a proof-carrying context layer, not a knowledge graph.

Different tool families answer different questions:

• Repo graph and index tools answer: what is connected to what.
• Semantic search and memory platforms answer: what stored text looks related to this query.
• Repo maps and plain file reads answer: what does the repo contain right now.
• Grape answers: what context is still valid, what changed since this session last saw it, what evidence supports it, and what can the next turn safely reuse.

Grape does not replace those tools. A graph index, repo map, or search tool can still find structure and candidates. Grape adds the context lifecycle on top: session ledgers, freshness checks against branch, commit, and dependency hashes, explicit invalidation, and proof-backed excerpts.

Claims in Grape carry proofs. A proof records the source hash and excerpt hash it came from, so the excerpt can be checked against current repo state instead of trusted on faith.

See section 2 of the V1 specification for the detailed comparison.

Why this matters

Most agent workflows still treat context as disposable text.

That breaks down on larger tasks because the agent needs more than search results. It needs to know:

• which files matter
• which rules apply
• which context it already saw
• which context changed
• which assumptions are stale
• which omitted context can be restored
• which safety constraints must be repeated
• which evidence supports a claim

Grape treats context like a build artifact.

It is compiled from repository state, linked to dependencies, scoped to a session, and invalidated when its inputs change.

Local-first by design

Grape runs against your local repository.

By default, it does not send repository content, artifacts, proofs, summaries, embeddings, or telemetry to a remote Grape service.

Local runtime state lives under .grape/. Grape keeps this state out of Git through .git/info/exclude.

Grape also:

• respects Git ignores and local privacy ignores
• excludes .grape/ runtime state from snapshots
• blocks common raw secret shapes before artifact output
• avoids exposing raw secret values in diagnostics
• separates raw evidence from assistant-written summaries
• prevents summaries from becoming durable proof

Repository content is still untrusted input. Source files, comments, docs, tests, and fixtures can contain prompt-injection text or private implementation details. Review context before forwarding it to an LLM, and keep real secrets in ignored files.

What Grape stores locally

Grape stores local runtime state under .grape/:

• .grape/config.json for local project setup
• .grape/grape.db for SQLite state, sessions, ledgers, proofs, source metadata, and scan diagnostics
• .grape/artifacts/ for generated JSON and Markdown context artifacts
• allowed source text rows for local lexical search
• rendered source or rule excerpts inside generated context artifacts
• restore metadata for omitted context
• proof and excerpt metadata for accepted exact source or rule spans
• observed command and test evidence from grape run and grape test, stored as hashes and metadata instead of raw stdout or stderr bodies

Grape does not send repository content, artifacts, proofs, summaries, embeddings, or telemetry to a remote Grape service by default. Your MCP client or coding agent may still forward returned context to its model provider. Treat Grape output like any other repo context you give an AI tool.

For bounded cleanup, run grape compact first. It previews eligible context artifact, compression cache, FTS, symbol metadata, orphan snapshot, and invalidated ledger cleanup. It also reports measured .grape, database, WAL, SHM, and artifact bytes before and after the run. It deletes nothing unless you rerun it with --confirm. FTS and symbol cleanup delete old rows by whole snapshot from their own tables. Snapshot cleanup deletes only orphan repo_snapshots with no source rows, context, indexes, compression rows, or dependencies. Invalidated ledger cleanup deletes old closed invalidation pairs only when the stale sent row and the marker that kept it inactive can be removed together. Compact does not delete source files, source records, claims, or proofs.

To inspect local storage without dumping bodies, run grape export. It returns a local inventory with storage bytes, row counts, and a source-text storage disclosure. It omits raw source files, FTS text bodies, context artifact bodies, database bytes, backing-file bodies, command output bodies, and ignored/private rejected file contents.

To remove local Grape state for one repository, preview the deletion first:

grape purge

Then confirm it:

grape purge --confirm
grape init --connect

grape purge --confirm deletes only the repo-local .grape/ directory after safety checks. It refuses symlinked local state, Git-tracked files under .grape/, mismatched config roots, and locked or contended sessions. It does not change source files, Git history, editor config, or MCP config.

How Grape works

Grape has three core stages.

1. Compile

Grape reads the working tree, branch state, source excerpts, project rules, manifests, observed command results, and narrow proof-backed claims.

It builds a ContextArtifact for the current task.

2. Track

Each artifact records the files, rules, proofs, config, branch state, manifests, and dependency hashes that shaped it.

When those inputs change, Grape can detect stale context instead of silently reusing it.

3. Diff

Grape compares the latest artifact with what the same agent session already received.

It then returns a ContextPack containing only the useful delta.

flowchart LR
  Agent[AI coding agent] --> MCP[MCP or CLI]
  MCP --> Compile[Compile context]
  Compile --> Artifact[Context artifact]
  Artifact --> Diff[Session diff]
  Diff --> Pack[Context pack]
  Pack --> Agent
  Repo[Git working tree] --> Compile
  State[(Local SQLite state)] --> Compile
  State --> Diff

Loading

Core guarantees

Grape is built around strict context rules:

• Repository state is the source of truth. Context comes from the working tree, branch state, rules, evidence, and local session ledger.
• Diffs are session-scoped. One session cannot omit context just because another session saw it.
• Pinned context is resent. Safety-critical rules and constraints are not optimized away.
• Stale context is invalidated. Branch, file, rule, config, manifest, and proof changes can invalidate prior context.
• Proof is not summary. Assistant-written summaries cannot promote themselves into durable truth.
• Compression is cache, not truth. Summaries may reduce repeated transport cost, but they do not prove behavior.
• Current context beats merely relevant context. Stale, private, branch-invalid, dirty-scope, or contradicted context is filtered before ranking.

What Grape is not

Grape is not:

• a chatbot
• a coding assistant
• a vector database
• a cloud memory platform
• a correctness prover
• a full repo graph daemon
• a replacement for tests or review

Grape does not prove that an agent’s answer is correct. It gives the agent better repository context to work with.

Language support

Grape currently has its strongest graph signal for TypeScript and JavaScript.

For other languages and text formats, Grape uses safe fallback behavior unless stronger support is proven through fixtures.

Fallback coverage includes:

• Python
• Java
• Kotlin
• Go
• Rust
• C#
• Ruby
• PHP
• Swift
• C
• C++
• shell
• JSON
• YAML
• TOML
• Markdown

Fallback does not mean ignored. It means Grape avoids pretending it has precise graph knowledge when it only has exact source, paths, lexical matches, or explicit references.

Benchmark evidence

Grape includes benchmark fixtures and scripts for local comparison. Recorded numbers are fixture evidence only. They are not production performance proof or claims that Grape beats naive context, search, or external tools unless a committed result file, command, date, and limits are named together.

Current benchmark output also reports per-turn local storage bytes for the temporary fixture workspace. Those fields help catch .grape/, database, WAL, and artifact growth regressions. They are fixture diagnostics, not production storage claims.

Transport fixtures

npm run bench exercises the installed package on named fixtures. On the three no-change transport fixtures from the recorded 2026-06-13 run, the second same-session turn reduced body-token context with zero unsafe omissions and zero stale sends:

Fixture	Turn 1 body tokens	Turn 2 body tokens	Reduction
clean-typescript-app	2811	1663	50.4%
polyglot-fallback-repo	3132	2523	31.46%
monorepo-lite-repo	3388	1885	52.07%

The current benchmark suite also covers branch-switch, dirty-worktree, stale-source, and session-reset invalidation fixtures.

That supports the core transport claim on these fixtures: Grape can omit unchanged same-session context, keep restore metadata for omitted items, and invalidate prior context when files, branches, or sessions change.

Published-package baselines

npm run bench:post-beta compares the published npm package with naive and search baselines on three small tasks. Results report file-level recall, known-noise ratio, layered output metrics, and rough serialized output size.

Post-beta baselines help answer whether Grape finds the right files and where known-irrelevant paths enter the compiled output. They do not prove token-size savings against naive or search, production readiness, or superiority over external tools.

See Benchmarks for commands, fixture names, result files, and caveats.

Project status

Grape 1.0.0 is the first stable release of the local context transport layer.

The 1.0 scope is local context transport, session-aware diffs, restore behavior, stale context invalidation, proof separation, MCP integration, client config helpers, and privacy-safe local storage.

Included in 1.0.0:

• global npm install through grape-context
• grape init --connect
• local SQLite runtime state
• CLI and MCP context retrieval
• session-aware context packs
• omitted context restore
• branch, source, and session invalidation
• dependency-tracked context artifacts
• exact source and rule proof rows
• narrow current-valid claims
• TypeScript and JavaScript indexing for common imports, exports, symbols, calls, and related test hints
• safe fallback for supported text files
• observed command and test evidence through grape run and grape test
• local check suite, benchmark fixtures, package smoke, and packaged MCP smoke

Experimental or not promised in 1.0:

• cloud sync
• broad agent memory
• full semantic ranking
• embeddings
• complete call graphs
• broad language-aware graph extraction
• automatic conflict resolution
• broad durable claim promotion
• benchmark superiority claims
• guaranteed behavior in every IDE MCP client without a human client trial

The stable release gate is documented in 1.0 readiness.

Development

Use the pinned toolchain:

npm ci

For most changes, run the local gate before you commit:

npm run check

npm run check runs docs, fixtures, memory smoke, architecture, storage, platform helpers, typecheck, package dry-run, Codex workflow, install smoke, and behavior tests.

Run narrower checks while you are iterating:

You changed	Run first	Run before commit
Docs or examples	npm run docs:check	npm run check
Fixture metadata	npm run fixtures:check	npm run check
TypeScript code	npm run typecheck and npm run test:behavior	npm run check
Storage migrations	npm run storage:check and npm run test:behavior	npm run check
Codex plugin or installer	npm run plugin:check and npm run codex:check	npm run check
Benchmark harness or fixtures	npm run benchmark:run	npm run check and npm run benchmark:run
Package contents	npm run package:check and npm run install:check	npm run check

Use the release-candidate gate when you need packaged workflow evidence:

npm run beta:check

npm run beta:check runs the local check suite, benchmark fixtures, and packaged client trial. The packaged trial validates installed CLI core workflows, Cursor and Claude Desktop install dry-runs, and stdio MCP behavior from an installed package. It is not a replacement for a human Cursor, Claude Desktop, or Claude Code UI trial when release policy requires one.

If a behavior test fails, start with the named folder under tests/behavior/. If a docs check fails, update the owning contract or example instead of patching around the script. Use docs/v1/README.md to find the owning domain doc before changing behavior.

After installing the published package globally, run:

npm run global:smoke

Documentation

Start here:

• Documentation index
• V1 documentation
• Implementation contract
• Architecture overview
• State machine
• Invariants
• Roadmap
• Contributing

Core references:

• Trust model
• Context artifact
• Context diff
• Agent sessions
• Compression
• Storage
• Security
• MCP tools
• CLI
• Testing
• Benchmarks

Contributing

Grape is not ready for broad feature expansion yet.

Contributions should preserve the implementation contract and avoid expanding the product surface before the current roadmap goal is proven.

Before contributing, read:

• Contributing guide
• Invariants
• Roadmap

Implementation standards:

• no godfiles
• no generic utility dumps
• no hidden state transitions
• no direct SQLite access outside storage repositories
• no summaries as proof
• no MCP writes that promote durable truth
• no stale dependency manifests in returned context

Star History

License

MIT