tapper

tapper

tapper is a CLI for building knowledge systems with KEGs (Knowledge Exchange Graphs), including personal knowledge management and agent memory workflows across domains.

Primary entrypoint:

• tap for the full CLI surface

Optional secondary entrypoint:

• keg as a pruned, project-focused profile built from the same command system

Problem This Solves

As notes grow across projects, domains, and tools, context gets fragmented:

• important details are buried in disconnected files
• links between ideas, plans, patches, releases, and people are hard to track
• humans and agents cannot reliably reuse the same memory and structure

tapper solves this by storing notes as linked KEG nodes with structured metadata, predictable config resolution, and CLI workflows for creating, navigating, and maintaining shared memory.

Installation

Homebrew (macOS and Linux)

brew install jlrickert/formulae/tapper

Optional: install the pruned project-local binary too:

brew install jlrickert/formulae/keg

Shell completions for zsh, bash, and fish are installed automatically.

From source

Prerequisite: Go 1.26.0 or newer.

go install github.com/jlrickert/tapper/cmd/tap@latest
go install github.com/jlrickert/tapper/cmd/keg@latest

If needed, add your Go bin directory to PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Set up shell completions manually:

# zsh (persist)
tap completion zsh > "${fpath[1]}/_tap"

Precompiled binaries

Download from GitHub Releases.

Verify installation:

tap --help

Quick Start

Create your first keg and start taking notes in under a minute.

1. Set up configuration

tap repo config edit

Opens your editor with the user config file (~/.config/tapper/config.yaml). Set fallbackKeg to personal (or your preferred alias) and configure kegSearchPaths so tapper knows where to find your kegs. Save and close.

2. Initialize a keg

tap repo init --keg personal

Creates a keg under your first kegSearchPaths entry and registers the alias.

3. Create a node

tap create

Opens your editor with a frontmatter template. Write your note, save, and close. Since fallbackKeg is set, no --keg flag needed.

4. View and edit a node

tap cat 1

On a terminal this opens the node in your editor for viewing and editing.

5. List all nodes

tap list

6. Search

tap grep "first"

That's it — you have a working knowledge base. See More Examples for snapshots, archives, and automation workflows.

Using With Claude Code

Register tapper as an MCP server to give Claude Code full access to your kegs:

claude mcp add --transport stdio tapper -- tap mcp

This exposes 31 KEG tools (read, write, search, index, snapshot, lock) directly in Claude Code — no per-command permission prompts needed.

See MCP Server Setup for details on per-tool keg targeting, manual JSON config, and troubleshooting.

More Examples

Target a specific keg from any command:

tap --keg personal list
tap --path ~/Documents/kegs/pub snapshot history 12

Initialize a project-local keg:

tap repo init --keg tapper --project

Create and inspect node history:

tap snapshot create 12 --keg personal -m "before refactor"
tap snapshot history 12 --keg personal

Export and import a keg archive:

tap archive export --keg personal -o notes.keg.tar.gz
tap archive import notes.keg.tar.gz --keg personal

Archive import overwrites matching node IDs in the target keg instead of allocating new node IDs. Snapshot history is included by default; use --no-history to export only the current node state.

The keg binary provides the same commands with project-local defaults:

keg snapshot create 12 -m "before refactor"
keg archive export -o notes.keg.tar.gz

Automation and scripting

Commands accept piped stdin for non-interactive use:

echo "Automated note" | tap create --keg personal
tap cat 1 --keg personal --content-only

When stdin is piped, no editor is launched. Use --content-only, --stats-only, or --meta-only with tap cat to get machine-readable output.

Configuration Quick Map

• User config: ~/.config/tapper/config.yaml
• Project config: .tapper/config.yaml
• Keg config: <keg-root>/keg

Documentation

Project docs live under docs/:

• Documentation Home
• Configuration Overview
• Architecture Overview
• CLI And Command Flow
• Service Layer
• Repository Layer
• Testing Architecture
• User Config
• Project Config
• Keg Config
• Resolution Order
• Configuration Examples
• Troubleshooting
• KEG Structure Patterns
• Minimum Keg Node
• Domain Separation And Migration
• Example Keg Structures
• Markdown Style Guide
• AI Coding Agent Configuration
• MCP Server Setup

Config Precedence At A Glance

When no explicit keg target is provided, tapper resolves in this order:

1. defaultKeg
2. kegMap path match (pathRegex first, then longest pathPrefix)
3. fallbackKeg

Alias lookup then prefers explicit kegs entries, then discovered aliases from kegSearchPaths, then project-local alias fallback at ./kegs/<alias>.

Troubleshooting

For common errors such as no keg configured, keg alias not found, and discovery path issues, see docs/configuration/troubleshooting.md.

Repository Layout

• cmd/tap - tap entrypoint
• cmd/keg - keg entrypoint
• pkg/tapper - config, resolution, and init services
• pkg/keg - KEG primitives and repository implementation
• kegs/tapper - repository KEG content
• docs/ - end-user documentation