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:

• kegv2 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

Prerequisite: Go 1.26.0 or newer.

Recommendation: install using the newest release tag (currently v0.2.0).

Install binaries from the newest tag:

go install github.com/jlrickert/tapper/cmd/tap@v0.2.0
go install github.com/jlrickert/tapper/cmd/kegv2@v0.2.0

Precompiled binaries are also published on GitHub Releases: https://github.com/jlrickert/tapper/releases (use the newest tag).

If needed, add your Go bin directory to PATH:

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

Verify installation:

tap --help

Optional: verify the pruned project-focused binary too:

kegv2 --help

Set up shell completions for tap:

# zsh (current session)
source <(tap completion zsh)

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

Optional: install completions for kegv2 if you use the pruned binary:

# zsh (current session)
source <(kegv2 completion zsh)

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

If new commands do not appear in tab completion after an upgrade, regenerate the completion files and reload your shell.

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 tapper --project

Use the current working directory instead of git root:

tap repo init tapper --cwd
tap repo init 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 kegv2 only when you specifically want the pruned project-local profile:

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

tap is the main command. kegv2 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:

kegv2 archive export -o notes.keg.tar.gz
kegv2 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 kegv2 workflow:

kegv2 archive export -o notes.keg.tar.gz
kegv2 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/kegv2 - kegv2 entrypoint
• pkg/tapper - config, resolution, and init services
• pkg/keg - KEG primitives and repository implementation
• kegs/tapper - repository KEG content
• docs/ - end-user documentation