Pantry

Local note storage for coding agents. Your agent keeps notes on decisions, bugs, and context across sessions — no cloud, no API keys required, no cost.

Features

• Works with multiple agents — Claude Code, Cursor, Codex, OpenCode, RooCode. One command sets up MCP config for your agent.
• MCP native — Runs as an MCP server exposing pantry_store, pantry_search, and pantry_context as tools.
• Local-first — Everything stays on your machine. Notes are stored as Markdown in ~/.pantry/shelves/, readable in Obsidian or any editor.
• Zero idle cost — No background processes, no daemon, no RAM overhead. The MCP server only runs when the agent starts it.
• Hybrid search — FTS5 keyword search works out of the box. Add Ollama, OpenAI, or OpenRouter for semantic vector search.
• Secret redaction — 3-layer redaction strips API keys, passwords, and credentials before anything hits disk.
• Cross-agent — Notes stored by one agent are searchable by all agents. One pantry, many agents.

Install

Download a binary (recommended)

1. Go to the Releases page and download the binary for your platform:

   | Platform | File | |----------|------| | macOS (Apple Silicon) | pantry-darwin-arm64 | | macOS (Intel) | pantry-darwin-amd64 | | Linux x86-64 | pantry-linux-amd64 | | Linux ARM64 | pantry-linux-arm64 | | Windows x86-64 | pantry-windows-amd64.exe |

2. Make it executable and move it to your PATH (macOS/Linux):

   chmod +x pantry-darwin-arm64
   mv pantry-darwin-arm64 /usr/local/bin/pantry
   

3. On macOS you may need to allow the binary in System Settings → Privacy & Security the first time you run it.

Initialize

pantry init

Connect your agent

pantry setup claude-code   # or: cursor, codex, opencode, roocode

This writes the MCP server entry into your agent's config file. Restart the agent and pantry will be available as a tool.

Run pantry doctor to verify everything is working.

Tell your agent to use Pantry

MCP registration makes the tools available, but your agent also needs instructions to actually use them. The setup command installs a skill file automatically for agents that support it (Claude Code, Cursor, Codex). For other agents — or if you prefer to use a project-level rules file — add the following to your AGENTS.md, .rules, CLAUDE.md, or equivalent:

## Pantry — persistent notes

You have access to a persistent note storage system via the `pantry` MCP tools.

**Session start — MANDATORY**: Before doing any work, retrieve notes from previous sessions:
- Call `pantry_context` to get recent notes for this project
- If the request relates to a specific topic, also call `pantry_search` with relevant terms

**Session end — MANDATORY**: After any task that involved changes, decisions, bugs, or learnings, call `pantry_store` with:
- `title`: short descriptive title
- `what`: what happened or was decided
- `why`: reasoning behind it
- `impact`: what changed
- `category`: one of `decision`, `pattern`, `bug`, `context`, `learning`
- `details`: full context for a future agent with no prior knowledge

Do not skip either step. Notes are how context survives across sessions.

Semantic search (optional)

Keyword search (FTS5) works with no extra setup. To also enable semantic vector search, configure an embedding provider using pantry config set or by editing ~/.pantry/config.yaml directly.

Ollama (local, free):

pantry config set --provider ollama
ollama pull nomic-embed-text

OpenAI:

pantry config set --provider openai --api-key sk-...

OpenRouter:

pantry config set --provider openrouter --api-key sk-or-...

Use --model to override the default model for a provider, and --base-url for custom endpoints:

pantry config set --provider openai --model text-embedding-3-large --api-key sk-...
pantry config set --api-key sk-...   # update key only, keep everything else

After changing providers, rebuild the vector index:

pantry reindex

Environment variables

All config file values can be overridden with environment variables. They take precedence over ~/.pantry/config.yaml and are useful when the MCP host injects secrets into the environment instead of writing them to disk.

| Variable | Description | Example | |----------|-------------|---------| | PANTRY_HOME | Override pantry home directory | /data/pantry | | PANTRY_EMBEDDING_PROVIDER | Embedding provider | ollama, openai, openrouter | | PANTRY_EMBEDDING_MODEL | Embedding model name | text-embedding-3-small | | PANTRY_EMBEDDING_API_KEY | API key for the embedding provider | sk-... | | PANTRY_EMBEDDING_BASE_URL | Base URL for the embedding API | http://localhost:11434 | | PANTRY_CONTEXT_SEMANTIC | Semantic search mode | auto, always, never |

Examples

Use OpenAI embeddings without putting the key in the config file:

PANTRY_EMBEDDING_PROVIDER=openai \
PANTRY_EMBEDDING_MODEL=text-embedding-3-small \
PANTRY_EMBEDDING_API_KEY=sk-... \
pantry search "rate limiting"

Point a second pantry instance at a different directory (useful for testing or per-workspace isolation):

PANTRY_HOME=/tmp/pantry-test pantry init
PANTRY_HOME=/tmp/pantry-test pantry store -t "test note" -w "testing" -y "because"

Pass the API key through the MCP server config so it is injected at launch time rather than stored on disk. Example for Claude Code (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "pantry": {
      "command": "pantry",
      "args": ["mcp"],
      "env": {
        "PANTRY_EMBEDDING_PROVIDER": "openai",
        "PANTRY_EMBEDDING_MODEL": "text-embedding-3-small",
        "PANTRY_EMBEDDING_API_KEY": "sk-..."
      }
    }
  }
}

Disable semantic search entirely for a single invocation (falls back to FTS5 keyword search):

PANTRY_CONTEXT_SEMANTIC=never pantry search "connection pool"

Commands

pantry init                  Initialize pantry (~/.pantry)
pantry doctor                Check health and capabilities
pantry store                 Store a note
pantry search <query>        Search notes
pantry retrieve <id>         Show full note details
pantry list                  List recent notes
pantry remove <id>           Delete a note
pantry notes                 List daily note files (alias: log)
pantry config                Show current configuration
pantry config init           Generate a starter config.yaml
pantry config set            Set a configuration value
pantry setup <agent>         Configure MCP for an agent
pantry uninstall <agent>     Remove agent MCP config
pantry reindex               Rebuild vector search index
pantry version               Print version

Storing notes manually

pantry store \
  -t "Switched to JWT auth" \
  -w "Replaced session cookies with JWT" \
  -y "Needed stateless auth for API" \
  -i "All endpoints now require Bearer token" \
  -g "auth,jwt" \
  -c "decision"

Flag reference

pantry store:

| Flag | Short | Description | |------|-------|-------------| | --title | -t | Title (required) | | --what | -w | What happened or was learned (required) | | --why | -y | Why it matters | | --impact | -i | Impact or consequences | | --tags | -g | Comma-separated tags | | --category | -c | decision, pattern, bug, context, learning | | --details | -d | Extended details | | --source | -s | Source agent identifier | | --project | -p | Project name (defaults to current directory) |

pantry list / pantry search / pantry notes:

| Flag | Short | Description | |------|-------|-------------| | --project | -p | Filter to current project | | --limit | -n | Maximum results | | --source | -s | Filter by source agent | | --query | -q | Text filter (list only) |

Under the hood

CGO-free, pure Go

Pantry is built without CGO. SQLite runs as a WebAssembly module inside the process via wazero — a zero-dependency, pure-Go WASM runtime. This means:

• No C compiler needed — go build just works, no gcc, musl, or zig required
• True static binaries — the distributed binaries have no shared library dependencies (ldd shows nothing)
• Cross-compilation is trivial — all five platform targets (GOOS/GOARCH) build from a single go build invocation with CGO_ENABLED=0
• Reproducible builds — no C toolchain version drift

The tradeoff: first query of a session pays a one-time ~10 ms WASM compilation cost. Subsequent queries are fast.

SQLite extensions

Two SQLite extensions are compiled into the binary as embedded WASM blobs:

sqlite-vec — vector similarity search. Pantry uses it to store note embeddings as 768- or 1536-dimensional float32 vectors in a vec0 virtual table, then retrieves the nearest neighbours with a single SQL query:

SELECT note_id, distance
FROM vec_notes
WHERE embedding MATCH ?
ORDER BY distance
LIMIT 20

The extension is loaded at connection open time via sqlite3_load_extension equivalent in the WASM host.

FTS5 — SQLite's built-in full-text search virtual table. Notes are indexed in an fts_notes shadow table using the porter tokenizer (English stemming). FTS5 handles keyword search when no embedding provider is configured, and also runs alongside vector search as a hybrid fallback.

Storage layout

Notes live in ~/.pantry/:

~/.pantry/
  config.yaml          # embedding provider, model, API key
  pantry.db            # SQLite database (WAL mode)
  shelves/
    project/
      YYYY-MM-DD.md    # daily Markdown files — human-readable, Obsidian-compatible

The SQLite database holds structured note data and search indexes. The Markdown files in shelves/ are ap