The Knowledge Base

A living wiki maintained by your AI agents. Documentation that never rots.

The Anti-Rot Layer

The Knowledge Base (KB) is persistent, cloud-hosted project documentation that actually stays in sync with your code. Unlike traditional wikis that go stale the moment you write them, the KB is designed to be updated automatically or on-demand by the AI itself.

When you explain your authentication system to Claude Code, the KB captures that architecture. The next time an agent - yours or a teammate's - asks about auth, they get that context instantly. No repetition required.

1. Structure & Hierarchy

Entries follow a logical hierarchy designed to fit into an LLM's context window efficiently. While the CLI mimics a file system, the data is secured in the cloud, independent of your git history. 

project/
├── onboarding/
│   ├── api           - API conventions and endpoints
│   ├── database      - Schema and migrations
│   └── testing       - Test patterns and fixtures
├── architecture/
│   ├── auth          - Authentication flow
│   └── caching       - Cache invalidation strategy
└── troubleshooting/
    └── common        - Frequent issues and fixes

Projects: Top-level containers, typically one per codebase.
Compartments: High-level categories (folders).
Entries: The actual knowledge documents (Markdown files).

2. Context Injection (Reading)

This is the mechanics behind the "Infinite Onboarding" solution.

When you initialize a session, Recalletta automatically fetches the relevant KB structure and injects it into the conversation's system prompt.

Your agent sees the project's documentation before writing its first reply. It transforms the agent from a confused new hire into a productive team member who knows exactly how the system is wired, what libraries you prefer, and which architectural patterns are strictly forbidden.

Important Entries

Entries marked as important are automatically injected into every session's context. Use this sparingly for critical information that every agent interaction needs.

3. Interactions (Writing)

You interact with the KB through the CLI, the Web Dashboard, or directly through your agent.

CLI Commands

# Browse the KB tree
recalletta kb
recalletta kb --full          # Include entry content

# Read specific entries
recalletta kb onboarding/api

# Search content
recalletta kb search "authentication"

# Create/Update entries
recalletta kb set onboarding/new-entry -t "Title" -b "Content"
recalletta kb set onboarding/critical -t "Critical" -b "Content" -i  # Mark as important

# Partial update (like Claude's Edit tool)
recalletta kb patch onboarding/api "old text" "new text"

# Version control
recalletta kb history onboarding/api      # View versions
recalletta kb diff onboarding/api 1 2     # Compare versions
recalletta kb rollback onboarding/api 3   # Restore version

# Delete
recalletta kb del onboarding/old-entry

Project Management

# List all projects
recalletta project list

# Create a new project
recalletta project create my-project

# Pin current directory to a project
recalletta pin my-project

Direct Agent Interaction

Since the agent has read/write intent access, you can simply instruct it in natural language:

  • "What does our KB say about authentication?"
  • "Check the troubleshooting guide for database issues."
  • "Add this decision to the KB under architecture/caching."

4. Maintenance Strategies

Keeping documentation alive is usually a chore. Recalletta offers two ways to handle this: the Manual Audit (Highly Recommended) and Periodic Review.

Strategy A: The Periodic Audit (Recommended)

This is the "bulk refactor" for your documentation. Instead of maintaining files daily, you treat the KB like code that needs occasional refactoring.

The Workflow:

  1. Open a session with your agent.
  2. Issue the audit prompt: "Review all code and current docs. Update our KB: add missing entries, remove obsolete ones, and restructure categories to match the current reality."
  3. The agent analyzes the diff between your actual code and your KB, then executes a series of updates.

Strategy B: Incremental Updates

As you work, ask the agent to update the KB when you make significant changes:

  • "We just changed the auth flow - update the KB."
  • "Add this gotcha to the troubleshooting section."
  • "The deployment process changed, document the new steps."

Safety: Immutable Versioning

Crucially, nothing is ever overwritten.

Every update - whether performed by you manually or by the agent - creates a new version of the entry. 

v1: The original entry.
v2: The agent adds a new API endpoint.
v3: You correct a typo.

The old versions are kept forever. If an agent hallucinates or deletes something important, you can instantly revert to the previous version via the Dashboard or CLI: 

recalletta kb rollback onboarding/api 2

Best Practices

What Belongs Here

  • Architecture Decisions: Why Postgres over MongoDB? Why this specific message queue?
  • Conventions: Naming patterns, folder structure, code style.
  • Onboarding Context: The "must-knows" for a new human (or synthetic) developer.
  • Troubleshooting: The fix for that obscure error that happens every Tuesday.
  • Gotchas: Things that trip you up repeatedly - document once, never forget.

What Does Not Belong

  • Secrets: API keys, passwords, tokens. (We scrub them, but don't tempt fate).
  • Ephemeral Info: Things that change hourly.
  • The Code Itself: That is what your repository is for. The KB is for the why, not the code.

Full CLI reference →