The knowledge base (KB) is picobot's persistent memory — a structured collection of markdown files with YAML frontmatter, organized by topic. It replaces nanobot's flat MEMORY.md approach with something that scales, searches, and syncs.

Why Not Just a Flat File?¶

Nanobot stored everything in a single MEMORY.md. Problems: - Agent stores the same insight repeatedly (no duplicate detection) - Search is slow (scan the whole file) - No privacy control (everything or nothing is shared) - No structure (notes about the user mixed with project knowledge)

The KB fixes all of these with topics, two-phase search, duplicate detection, and per-topic sharing.

Topics¶

Knowledge is organized into five topic directories:

The distinction matters: journal/ is for raw captures that may later be promoted to stable knowledge in other topics via the self-improvement pipeline. self/ is for processed, verified knowledge about the agent's own behavior.

Entry Format¶

Every KB entry is a markdown file with YAML frontmatter:

---
title: Python asyncio patterns for concurrent tool execution
topic: domains
tags: python, asyncio, concurrency, tools
created: 2026-02-15T10:30:00
updated: 2026-02-15T10:30:00
---

When running multiple tool calls concurrently, use `asyncio.gather()` with
`return_exceptions=True` to prevent one failure from canceling all tasks...

Using the KB Tool¶

Search Before Store¶

The most important pattern: always search before storing. This gives context, helps write better entries, and avoids duplicates.

kb(action="search", query="asyncio patterns")

Search is two-phase: 1. Phase 1: Match against YAML frontmatter (title, tags) — fast, precise 2. Phase 2: Full-text search across file content — catches everything else

Optionally scope to a topic:

kb(action="search", query="asyncio", topic="domains")

Store¶

kb(action="store", topic="domains", title="Python asyncio patterns", content="...", tags=["python", "asyncio"])

Before storing, the KB checks for duplicates: - Title overlap >60%: Likely the same entry, store is skipped - Content overlap >70%: Same content, different title — also skipped

Tags should be 2-5 lowercase, hyphenated terms.

Read¶

kb(action="read", path="domains/python-asyncio-patterns.md")

List Topics¶

kb(action="topics")

Returns each topic with its entry count.

Context Injection¶

The root knowledge/README.md is injected into every system prompt. This is the KB's summary — a high-level map of what the agent knows. Keep it concise and current.

Each topic also has a README.md with Handlebars-style templates that guide how entries in that topic should be written.

Git Sync¶

Share knowledge across picobot instances using git:

picobot kb sync --remote git@github.com:you/picobot-kb.git

Or set it in config:

{
  "knowledge": {
    "remote": "git@github.com:you/picobot-kb.git"
  }
}

The agent can also trigger sync from within a conversation:

kb(action="sync")

Privacy Control¶

sharing.yaml at the KB root controls which topics sync:

self: private
user: private
journal: private
projects: shared
domains: shared

Private topics are added to .gitignore and never pushed to the remote. The defaults protect personal data while sharing project and domain knowledge.

Conflict Resolution¶

When syncing, conflicts are resolved by last-write-wins (LWW) on the YAML updated timestamp. The entry with the more recent updated field wins. This is simple and predictable — no CRDTs, no merge dialogs.

File-per-entry format means conflicts are rare in the first place. Two agents would need to edit the exact same entry at the same time.

Obsidian Compatibility¶

The KB format (markdown + YAML frontmatter + topic directories) is Obsidian-compatible. Point Obsidian at ~/.picobot/workspace/knowledge/ for a visual knowledge browser with graph view, backlinks, and search. This works out of the box — no conversion needed.

Best Practices¶

• One concept per entry. A focused entry is findable; a kitchen-sink entry isn't.
• Descriptive titles. "Python asyncio patterns for concurrent tool execution" not "asyncio stuff."
• Use journal/ for raw captures. Don't overthink where something goes — dump it in journal/ and let the self-improvement pipeline promote it later.
• Keep README.md current. The root README is injected every turn — it's the agent's map of what it knows.
• Let duplicate detection work. Don't manually check for duplicates; the 60%/70% thresholds handle it.