Punchcard

Punchcard is a local-first context and governed-memory system for Cursor and Codex. It was validated on Ubuntu 24.04 and targets Debian and Ubuntu.

The system combines cited documentary retrieval, bounded task decks, append-only memory events, allowlisted validation, and transactional promotion. Failed attempts stay in searchable history; they never become current knowledge.

Punchcard owns its governed-memory implementation. CodeGraph is an optional independent project: Punchcard can recommend it and validate its public CLI/MCP contract, but does not install, configure, or access its storage.

What Punchcard does

Installing Punchcard adds rules, skills, and an MCP server to your agent (Cursor or Codex). The agent uses them automatically as it works; you don't run them by hand or pick a "mode". What changes is how much context the agent gathers and how it records what it learns:

• Quick, well-defined questions — when the relevant files are already known, the agent just reads them. Punchcard stays out of the way and adds no overhead.
• Open-ended work (debugging, refactors, exploring unfamiliar code) — Punchcard builds a bounded evidence deck: cited documentary retrieval over your docs and code, plus relevant past decisions. The agent grounds its work in real source instead of guessing, while staying within a token budget.
• Changes that should outlive the session — Punchcard records them as project memory only after your configured validations (format, build, tests, lint) pass on the same code. Failed attempts stay in searchable history; they never become current knowledge.

The result is more accurate, better-grounded agent work with less wasted context, and a memory of decisions and constraints that future sessions can recall.

The exact policy that drives this behavior lives in the generated punchcard.md and .cursor/rules/punchcard.mdc; you normally never edit these.

Setup

Host dependencies:

./scripts/setup.sh

Binary, project init, and first index:

cargo install --path crates/punchcard-cli --locked
punchcard init
punchcard rag index
punchcard doctor

punchcard init defaults to the code RAG profile (CodeRankEmbed INT8 plus BM25). Use --rag-profile fast when resource use matters more than code-specific retrieval. The first index downloads the pinned model into .punchcard/rag/models. See Documentary retrieval for models and switching.

Each initialized repository gets its own .punchcard/config.toml (created by punchcard init). See Configuration for all options.

Agent integration

Plugin install (preferred):

punchcard plugin install all --local-source ./plugins
punchcard plugin status

For repository development, agent policy is authored in crates/punchcard-rules/assets. Regenerate bundles with:

./scripts/agent-assets.sh sync
./scripts/agent-assets.sh check

./scripts/validate.sh runs the check as part of the full validation pass.

For agents without a packaged plugin, see Ecosystem compatibility.

Governed workflow example

punchcard deck prepare "change the public API"
punchcard change begin --title "API v2" --summary "The API uses v2."
punchcard validate fmt --change-id <change-id>
punchcard validate check --change-id <change-id>
punchcard validate test --change-id <change-id>
punchcard validate clippy --change-id <change-id>
punchcard change promote <change-id> --file src/lib.rs

Other useful commands: rag search, memory search, memory search --archive, stats, doctor.

Documentation

• Architecture
• Configuration
• Memory model
• Setup
• Ecosystem compatibility
• Documentary retrieval
• Cursor integration
• Codex integration
• Plugin lifecycle
• CodeGraph compatibility
• Validation
• Security