Tapper is a CLI and MCP server for building a centralized brain across an organization. It gives teams and AI agents one durable place to store project context, decisions, handoffs, plans, incidents, links, and working knowledge.
The core unit is a KEG: a Knowledge Exchange Graph made of markdown nodes with metadata, links, tags, search indexes, and snapshot history. Humans can use it from the terminal. Agents can use the same memory through MCP.
Organizations lose context in familiar ways:
- new teammates spend days reconstructing project history
- release decisions live in chat threads, tickets, and private notes
- AI agents start each session without the background the last session learned
- cross-team handoffs depend on whoever remembers the details
- documentation explains the code, but not why the system is shaped that way
Tapper turns that scattered memory into a queryable, linked, auditable knowledge base. A team can capture a decision once, link it to the project, tag the domain, snapshot important edits, and let both people and agents retrieve it later.
Use Tapper for the context that should survive beyond a single conversation or ticket:
- architecture decisions and tradeoffs
- project onboarding notes
- release plans and post-release findings
- customer, domain, or operational knowledge
- runbooks, debugging notes, and incident timelines
- agent instructions and memory for long-running work
- links between people, systems, repos, features, and decisions
Tapper is not a replacement for source control, issue trackers, or docs sites. It connects the memory around them.
brew install jlrickert/formulae/tapperOptional project-local profile:
brew install jlrickert/formulae/kegPrerequisite: Go 1.26.0 or newer.
go install github.com/jlrickert/tapper/cmd/tap@latest
go install github.com/jlrickert/tapper/cmd/keg@latestIf needed, add your Go bin directory to PATH:
export PATH="$(go env GOPATH)/bin:$PATH"Download from GitHub Releases.
Verify installation:
tap --helpThis path creates a local knowledge base and makes plain tap commands resolve
to it.
tap bootstrap --kind local --default-keg @local/personal
tap keg create @local/personal
tap use @local/personal --userCreate your first memory:
tap createWrite a short note in your editor, for example a project decision or onboarding fact. Then read, list, and search it:
tap list
tap cat 1
tap grep "decision"The important thing is the workflow: capture context close to the work, then retrieve it by ID, link, tag, or search when a human or agent needs it later.
For a team or company, use a shared hub and namespace so everyone works against the same organizational memory.
tap bootstrap --kind cloud
tap auth login
tap namespace create acme
tap keg create @acme/engineering
tap use @acme/engineeringAdd teammates to the namespace or grant access to a specific keg:
tap namespace add-member @teammate editor --namespace acme
tap keg grant @teammate editor --keg @acme/engineering
tap keg rename @acme/engineering docsTypical team layout:
@acme/engineeringfor architecture, releases, incidents, and repo context@acme/productfor product decisions, customer knowledge, and roadmap context@acme/opsfor runbooks, operational notes, and incident follow-up
Use separate kegs when access boundaries or domains differ. Use links when one domain needs to point at another.
Tapper exposes the same memory to AI agents through MCP. The agent can search, read, create, edit, snapshot, and orient itself against a keg without scraping files directly.
tap integrate codex
tap integrate claudetap integrate HOST is the official supported installation, refresh, upgrade,
plugin-selection, and scope surface. Each command extracts the host-native
marketplace embedded in tap, registers the local source, and installs the
baseline tapper plugin. The tap executable on PATH must be current enough
to provide the Go-backed tap hook commands used by the plugin. No GitHub
checkout or manual MCP configuration is required. Repeat --plugin to add
optional plugins, for example tap integrate claude --plugin tapper-dev.
Requested plugins keep their order and duplicates are ignored. Activation
defaults to --scope user; Claude also supports project (shared project
settings) and local (gitignored project settings), while Codex currently
supports only user. Use --dry-run to inspect every extraction path and host
command without side effects.
Refreshing is atomic and removes legacy packaged Python hooks. Review and trust the replacement hooks again, then start a fresh Codex thread or Claude session so the new hook commands and MCP connection take effect. Manual MCP setup is reserved for generic hosts without a native Tapper plugin.
See Using Tapper From AI Agents for setup, agent conventions, flight-first orientation, and manual MCP configuration.
Capture something worth remembering:
tap create --keg @acme/engineeringFind related context:
tap grep "billing migration" --keg @acme/engineering
tap tags "release and payments" --keg @acme/engineering
tap backlinks 42 --keg @acme/engineeringPreserve an important state before changing it:
tap snapshot create 42 --keg @acme/engineering -m "before release edits"
tap snapshot history 42 --keg @acme/engineeringMove a repository or session onto the right shared memory:
tap use @acme/engineering
tap use @acme/engineering --flight @acme/+release-42Export a keg for backup or migration:
tap archive export --keg @acme/engineering -o engineering.keg.tar.gz
tap archive import engineering.keg.tar.gz --keg @acme/engineering- KEG: a Knowledge Exchange Graph, usually scoped to a team, project, or domain.
- Node: one markdown memory entry with metadata, tags, links, stats, and optional files/images.
- Hub: where kegs live. A hub can be local, hosted, or enterprise.
- Namespace: the owner or organization segment in references such as
@acme/engineering. - Flight: task context that can cap kegs for MCP sessions and inject agent instructions for a task.
- MCP: the protocol Tapper uses to expose KEG operations to AI agents.
Start here:
- Documentation Home
- Configuration Overview
- Using Tapper From AI Agents
- KEG Structure Patterns
- Backups And Archives
- Node Snapshots
- Query Expressions
For contributors and internals:
Tapper resolves a keg reference through this chain:
- explicit CLI flags such as
--keg,--namespace, and--hub - project config in
.tapper/config.yaml - user config in
~/.config/tapper/config.yaml - built-in defaults, unless disabled
A keg reference is usually a bare name or @namespace/name. The namespace
selects the hub, and the hub selects the backend. Local kegs live at
<basePath>/@<namespace>/<name>.
Only user config may define hubs and credentials. Project config can select defaults for a repository, but it cannot introduce a new hub target or token. See Resolution Order.
--flight is a task context for orientation and MCP sessions.
Direct CLI commands still use normal keg authorization and do not have their
access reduced by flight cover caps.
Persist a project flight with either tap use --flight @namespace/+slug or the
default-namespace shorthand tap use +slug. A config-driven MCP connection
adopts that selection only after an explicit orient call. A launcher-bound
tap mcp --flight REF connection keeps its flight identity for the process
lifetime while each orientation refreshes that flight's current details.
main is the GitHub default branch and the release branch. The next branch is
used for upcoming release work when active. Use the repository's current branch
or maintainer guidance when opening a PR.
Releases are cut by dispatching the Release workflow, which writes the changelog commit and tag, then runs GoReleaser.
cmd/tap- full CLI entrypointcmd/keg- project-local CLI profilepkg/tapper- config, resolution, hub, and service layerpkg/keg- KEG primitives and repository implementationpkg/mcp- MCP server and tool surfacedocs/- user and contributor documentation