Knowledge Management

Crosslink’s knowledge system provides shared documentation that syncs across agents via a dedicated crosslink/knowledge git branch. Agents can save research findings, architectural decisions, and reference material that persists across sessions and is available to all agents.

Overview

Knowledge pages are markdown documents with YAML frontmatter. They live on the crosslink/knowledge branch (separate from your code) and are synced automatically when agents start sessions.

crosslink knowledge add api-auth-patterns \
  --title "API Authentication Patterns" \
  --tag architecture --tag security \
  --source "https://example.com/auth-guide" \
  --content "Summary of auth patterns evaluated..."

Creating Pages

Basic Page

crosslink knowledge add my-topic \
  --title "My Research Topic" \
  --content "Findings from investigating..."

The first argument is the slug – a URL-safe identifier used to reference the page.

With Tags and Sources

crosslink knowledge add rate-limiting \
  --title "Rate Limiting Strategy" \
  --tag architecture \
  --tag performance \
  --source "https://example.com/rate-limits" \
  --content "After evaluating token bucket vs sliding window..."

Tags and sources are repeatable – add as many as needed.

From a Design Document

crosslink knowledge add auth-design --from-doc DESIGN-AUTH.md

Imports a design document directly as a knowledge page.

Browsing Pages

List All Pages

crosslink knowledge list
crosslink knowledge list --json

Filter by Tag, Contributor, or Date

crosslink knowledge list --tag architecture
crosslink knowledge list --contributor agent-1
crosslink knowledge list --since 2026-03-01

View a Page

crosslink knowledge show api-auth-patterns

Searching

Full-Text Search

crosslink knowledge search "token bucket"
crosslink knowledge search "authentication" --context 3

The --context flag controls how many lines around each match are shown (default: 1).

Filter Search Results

crosslink knowledge search "caching" --tag performance
crosslink knowledge search "oauth" --source "example.com"
crosslink knowledge search "migration" --since 2026-03-01
crosslink knowledge search "retry logic" --contributor agent-2

Editing Pages

Append Content

crosslink knowledge edit rate-limiting \
  --append "Update: switched to sliding window after load testing"

Replace Content

crosslink knowledge edit rate-limiting \
  --content "Completely revised strategy based on new requirements..."

Add Tags or Sources

crosslink knowledge edit rate-limiting \
  --tag "load-testing" \
  --source "https://example.com/new-reference"

Removing Pages

crosslink knowledge remove rate-limiting

Syncing

Knowledge pages sync automatically during crosslink session start and crosslink sync. To force a manual sync:

crosslink knowledge sync

Conflict Resolution

When two agents edit the same page concurrently, crosslink uses an accept-both merge strategy: both versions of the content are preserved with clear markers, so no work is lost.

Bulk Import

Import existing markdown files as knowledge pages:

crosslink knowledge import ./docs/research/
crosslink knowledge import ./docs/ --tag imported --overwrite
crosslink knowledge import ./notes/ --dry_run  # preview without writing

Auto-Injection

Relevant knowledge pages are automatically injected into agent context at session start. The session-start.py hook and the knowledge MCP server work together to surface pages that match the agent’s current work.

This means research done by one agent is automatically available to other agents working on related issues.

Workflow Tips

Save research as you go. When you read API docs, evaluate libraries, or investigate a bug, save findings to a knowledge page so other agents (and future sessions) benefit.
Use descriptive slugs. api-auth-patterns is better than research-1.
Tag consistently. Use tags like architecture, security, performance, debugging, api, dependency to make pages discoverable.
Include sources. Link to the original documentation, blog post, or discussion that informed the page.

Command Reference

Command	Description
`knowledge add <slug>`	Create a new page
`knowledge show <slug>`	Display a page
`knowledge list`	List all pages
`knowledge edit <slug>`	Update a page
`knowledge remove <slug>`	Remove a page
`knowledge sync`	Manually sync from remote
`knowledge search <query>`	Full-text search
`knowledge import <directory>`	Bulk import markdown files