Knowledge Base (KB)

The Knowledge Base stores curated project knowledge -- architecture decisions, coding conventions, gotchas -- in a hierarchical structure. KB entries are written by agents at the user's request, not hand-authored by users. Users can view and edit entries via the web dashboard at recalletta.ai.

Entries marked as important are eligible for auto-injection on session start when project detection/pinning succeeds. Keep important entries compact: every important entry consumes agent context window, and over-marking entries as important degrades agent performance.

View the KB Tree

$ recalletta kb

or with full content:

$ recalletta kb --full

Real output:

$ recalletta kb tree
=== Knowledge Base (40 entries) ===

recalletta 70d90af5 Recalletta
├── agents Agents (1 entries)
│   └── self-awareness - Self-Aware Agents
├── meta Meta (5 entries)
│   ├── philosophy - Collaboration Philosophy
│   ├── memory-management - Memory Management Architecture
│   └── ...
├── gotchas Gotchas (19 entries)
│   ├── commits - Git Commit Style
│   ├── api-contract-mismatch - API Contract Mismatches Fail Silently
│   └── ...
├── crew Crew (9 entries)
│   ├── axiom - Axiom (Architect)
│   ├── data - Commander Data (Team Lead)
│   └── ...
└── onboarding Onboarding (1 entries)
    └── start - Quick Start for Recalletta

Read an Entry

Use a 2-part or 3-part path:

$ recalletta kb gotchas/commits              # 2-part: compartment/entry (current project)
$ recalletta kb recalletta/gotchas/commits   # 3-part: project/compartment/entry

Output:

$ recalletta kb gotchas/commits
# Git Commit Style

Do NOT add 'Generated with Claude Code' or 'Co-Authored-By: Claude' footers
to commits. User has corrected this multiple times. Just write clean commit
messages focused on what changed and why.

Create or Update an Entry

$ recalletta kb set <path> -t "Title" -b "Body content"

Flag	Purpose
-t "Title"	Entry title (required for new entries)
-b "Body"	Entry body (or pipe via stdin)
-i	Mark as important (eligible for auto-injection when project detection/pinning succeeds)

Examples:

$ recalletta kb set gotchas/my-entry -t "My Gotcha" -b "Don't do this because..."
$ recalletta kb set gotchas/my-entry -t "My Gotcha" -i -b "Eligible for injection when project detection succeeds"
$ echo "Body from stdin" | recalletta kb set gotchas/my-entry -t "Title"

Patch an Entry

Make a partial string replacement (like Claude Code's Edit tool):

$ recalletta kb patch <path> "old text" "new text"

Search the KB

$ recalletta kb search "query"

Output:

$ recalletta kb search "session"
Found 24 result(s) for 'session':
  recalletta/gotchas/fork-session-hooks - Fork sessions trigger session_end hooks
  recalletta/reference/sessions - Key Sessions
  ...

Version History

Every edit creates a new version. You can view history, compare versions, and rollback.

$ recalletta kb history <path>           # Show all versions
$ recalletta kb diff <path> [V1] [V2]    # Compare two versions
$ recalletta kb rollback <path> [V]      # Rollback to a previous version

Delete an Entry

$ recalletta kb del <path> [-y]

Pass -y to skip the confirmation prompt.

List All Entries

$ recalletta kb list

Shows all projects and their entries in a flat list.

Manage Compartments

$ recalletta kb compartment create <project> <name>
$ recalletta kb compartment rename <project> <old> <new>
$ recalletta kb compartment delete <project> <name> [-y]

Pending Updates

$ recalletta pending

Shows any KB updates that are queued but not yet applied. Note: pending is a top-level command, not a kb subcommand.

Context Override

Use -c to override the project context:

$ recalletta kb -c personal tree         # Personal workspace
$ recalletta kb -c myproject tree        # Specific project by slug