Knowledge Base

The persistent, searchable knowledge store for your project.

The knowledge base holds all durable project knowledge — sessions, decisions, tasks, research notes, and ingested documents. It supports keyword, semantic, and hybrid search across all entity types.

What goes in the knowledge base?

The knowledge base is the single source of truth for a project's accumulated knowledge. It stores both structured entities (created through workflows) and unstructured documents (ingested manually or by agents).

Structured entities are created through Nexus workflows:

• Sessions — execution history with append-only entries
• ADRs — architectural decisions with full lifecycle
• Tasks — work items with status and notes
• Dispatches — coordination records between agents and projects

Unstructured content is ingested via the doc_* tools:

• Research notes and analysis
• Reference material
• Scan reports (auto-ingested from security and performance scans)
• Planning items

Entity types

Searching

Use kb_search with three search modes:

Keyword search

Fast, exact matching using full-text search:

{
  "tool": "kb_search",
  "query": "RLS policy",
  "project_id": "...",
  "search_mode": "keyword"
}

Semantic search

Uses OpenAI embeddings (requires NEXUS_SEC_OPENAI_API_KEY) for meaning-based retrieval:

{
  "tool": "kb_search",
  "query": "how do we handle authorization?",
  "project_id": "...",
  "search_mode": "semantic"
}

Hybrid search

Combines keyword and semantic search for the best of both worlds:

{
  "tool": "kb_search",
  "query": "dispatch routing architecture",
  "project_id": "...",
  "search_mode": "hybrid",
  "entity_types": ["decision", "session"]
}

Related entities

Use kb_related to navigate the knowledge graph — find entities related to a given item:

{
  "tool": "kb_related",
  "entity_type": "decision",
  "entity_id": "..."
}

Document ingestion

Push content into the knowledge base via doc_ingest:

{
  "tool": "doc_ingest",
  "project_id": "...",
  "title": "API rate limiting analysis",
  "body": "## Findings\n\n...",
  "source": "research"
}

Documents start as unclassified and can be promoted to a specific classification.

Classification

Ingested documents can be classified to improve search relevance and organization:

MCP tools