The Knowledge Base Work in Progress

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. 

kb/
├── 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

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.

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"

# Manual Create/Update
recalletta kb set onboarding/new-entry -t "Title" -b "Content"

# Delete
recalletta kb del onboarding/old-entry

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 Auto-Maintenance.

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: Auto-Maintenance (Experimental)

Currently in the lab. Recalletta watches your background sessions to extract knowledge automatically:

  • New architecture decisions
  • Bug fixes worth remembering
  • Configuration patterns

Safety: Immutable Versioning

Crucially, nothing is ever overwritten.

Every update - whether performed by you manually, by the agent during an Audit, or via Auto-Maintenance - 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 during an audit, you can instantly revert to the previous version via the Dashboard or CLI.

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.

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.

Hive Mind

In a team workspace, the Knowledge Base is shared. When one developer documents a tricky deployment process via an Audit or a manual entry, every other agent on the team learns it instantly.

It creates a collective intelligence: the KB becomes more comprehensive than any single engineer's perspective because it accumulates the aggregate insights of the entire team's sessions.

Full CLI reference →