Brain Entries
Adding, searching, pinning, and managing knowledge entries.
Brain Entries
Brain entries are the individual knowledge records that make up Kavi's persistent memory. Each entry has a source type, content, tags, and scoring metadata that determines when and how it surfaces in agent context.
Source Types
Entries are created from five distinct sources, each capturing a different kind of knowledge:
| Source Type | When Created | What It Captures |
|---|---|---|
task | Task completes successfully | Title, summary, changed file paths, routing reason |
mission | Mission reaches a milestone | Mission-level context, goal summary, plan metadata |
landing | kavi land succeeds | Merge summary, validation results, integration notes |
operator | Manually added by the operator | Domain knowledge, constraints, preferences, corrections |
pattern | Mission starts with matching patterns | Promoted pattern data: title, summary, example paths, commands |
Search and Scoring
Brain search uses full-text token-based scoring to find relevant entries. When you search or when Kavi selects entries for task context, entries are ranked by a composite score.
Text Normalization
Before matching, both the query and entry content are normalized:
- Convert to lowercase
- Keep alphanumeric characters, slashes, and dashes
- Split into tokens of 3 or more characters
Search Scoring Weights
| Match Type | Score | Description |
|---|---|---|
| Exact title match | +4 | The query exactly matches the entry title |
| Token hit | +3 | A query token appears in the entry title or content |
| Substring match | +1 | A query token is a substring of a title or content token |
| Pinned entry | +5 | The entry is pinned (always added) |
Relevance Selection for Task Context
When Kavi selects brain entries to include in an agent's task context, additional scoring adjustments apply:
| Factor | Score | Description |
|---|---|---|
| Pinned | +5 | Base boost for pinned entries |
| Same mission | +6 | Entry belongs to the same mission as the current task |
| Path-tag match | +4 | Entry tags match file paths involved in the current task |
| Pattern source | +2 | Entry originated from a promoted pattern |
Entries are ranked by their combined score and the top results are included in the agent prompt.
Deduplication
When a new entry would duplicate an existing one (identical title and content), Kavi merges them instead of creating a duplicate:
- Tags from both entries are combined (union)
- Timestamps are updated to the latest values
- Pinned status is never overridden -- if the existing entry is pinned, it stays pinned regardless of the incoming entry's pinned state
This ensures the brain stays clean without losing metadata or operator-set pin flags.
CLI Commands
Use the following commands to manage brain entries:
# List all brain entries, or search with a query
kavi brain
kavi brain "routing decision"
# Pin an entry so it always appears in agent context
kavi brain-pin <entry-id>
# Unpin an entry to return it to score-based selection
kavi brain-unpin <entry-id>kavi brain without arguments lists all entries sorted by recency. With a query argument, it performs full-text search and displays results ranked by score. Pinned entries are visually marked in the output.