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/tapperPrerequisite: Go 1.26.0 or newer.
go install github.com/jlrickert/tapper/cmd/tap@latestIf needed, add your Go bin directory to PATH:
export PATH="$(go env GOPATH)/bin:$PATH"Download from GitHub Releases.
Verify installation:
tap --helpTapper stores KEGs in a Tapper Hub. Bootstrap the hosted service or provide an enterprise Hub endpoint, then authenticate.
tap bootstrap --kind cloud
tap auth login
tap keg create @alice/personal
tap use personal --userCreate your first memory:
tap node createWrite a short note in your editor, for example a project decision or onboarding fact. Then read, list, and search it:
tap node list
tap node read 1
tap node search "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 claude
tap integrate opencodetap integrate HOST is the official supported installation, refresh, upgrade,
plugin-selection, and scope surface. Each command extracts the host-native
plugins embedded in tap and installs the baseline tapper plugin together
with the tapper-guard safety plugin. Claude and Codex are driven through
their own plugin CLI, and the tap executable on PATH must be current enough
to provide the Go-backed tap hook commands their plugins use. opencode has no
plugin CLI, so tap merges the MCP server into its opencode.json, writes the
skills itself, and installs the guard as a plugin module. No GitHub checkout or
manual MCP configuration is required.
tapper-guard is a separate plugin so the PreToolUse guard — which denies
direct agent use of tap and keg and mutation of Tapper config — can be
disabled on its own without giving up the MCP server, the skill, or Codex's
orientation hook. --no-safety skips installing it; disabling or removing a
guard a host already has is done through that host, for example claude plugin disable tapper-guard@tapper-local. On opencode the guard is a
tool.execute.before plugin module calling the same tap hook pre-tool-use
binary; there --no-safety deletes the installed file, because opencode has no
command to disable a plugin.
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), opencode
supports project, and Codex is user-only because its CLI has no scope flag.
Use --dry-run to inspect every extraction path and host command or file write
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 node create --keg @acme/engineeringFind related context:
tap node search "billing migration" --keg @acme/engineering
tap node grep 'BILL-[0-9]+' --keg @acme/engineering
tap tag list "release and payments" --keg @acme/engineering
tap node backlinks 42 --keg @acme/engineeringPreserve an important state before changing it:
tap snapshot create 42 --keg @acme/engineering -m "before release edits"
tap snapshot list 42 --keg @acme/engineeringMove a repository or session onto the right shared memory:
tap use @acme/engineering
tap use @acme/engineering --flight @acme/+release-42
tap info
tap url 42 --opentap info shows the hub you are signed in to, the default keg, the active
flight, and the kegs that flight covers. tap url [REF] prints the hub web
link for the current keg, a node (42, @acme/engineering/42), a flight
(+release-42), or a namespace (@acme); --open also opens it in the
browser. Agents get the same link from the MCP url tool. tap explore kegs|flights|people QUERY
searches the hub's public directory; your own kegs come from tap keg list.
Export 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 remote Hub that owns the KEG.
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. The next MCP connection pins that
selection as its root. Within a connection, every
authority-bearing MCP call reloads the live bounded graph, defaults to the
root, and may select an accessible transitive descendant; configuration changes
cannot replace the root.
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 entrypointpkg/tapper- config, resolution, hub, and service layerpkg/keg- KEG primitives, remote client, and Hub-side orchestrationpkg/mcp- MCP server and tool surfacedocs/- user and contributor documentation