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

Run the CLI:

tap --help

Target a keg from the root command:

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

Initialize a project-local keg:

tap repo init --keg tapper --project

Use the current working directory instead of git root:

tap repo init --keg tapper --cwd
tap repo init --keg tapper --path .

Create and inspect node history with tap:

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

Use keg only when you specifically want the pruned project-local profile:

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

tap is the main command. keg exists to prove that the same Cobra tree can be exposed through a narrower profile with project-local defaults.

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

Export and import a keg archive:

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

Primary tap workflow:

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

Project-local keg workflow:

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

Archive import overwrites matching node IDs in the target keg instead of allocating new node IDs.

Snapshot history is included in archives by default. Use --no-history when you want to export only the current node state.

Show merged repo configuration:

tap repo config

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
• Entity And Tag Patterns
• Domain Separation And Migration
• Example Keg Structures
• Markdown Style Guide

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