Setting up your first knowledge base

This document outlines how to set up your first knowledge base.

Goal

Set up a knowledge base session for your repository and interact with it via chat.

Prerequisites

An LLM API key must be exposed via environment variables.

Steps

  • Initialize your knowledge base: Run kb init in your repository’s root directory. This command creates the foundational knowledge base structure by setting up the .kb-index.sqlite database in your repository’s root directory, which will store your knowledge.
  • Add content to your knowledge base: After initialization, you will need to add documents or other relevant content to your knowledge base using kb add commands.
  • Start a chat session: Once content is indexed, you can begin interacting with your knowledge base via chat by running kb chat.

Verification

To confirm kb init was successful, verify that the .kb-index.sqlite file has been created in your repository’s root directory.

After adding content, you can verify the overall setup by querying the knowledge base via chat or by using commands like kb query, kb graph, or kb docs. Note that kb query is designed for programmatic, one-shot retrieval by agents, whereas chat mode offers an iterative, user-facing conversational experience.

References

  • installSkillIntoProject() targets user profile-level MDs (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md) rather than local repo CLAUDE.md/AGENTS.md. If neither profile MD exists, it creates ~/.claude/CLAUDE.md. The cwd parameter was removed from the function signature. — fact://0c5223b17f53aab1
  • kb query is the agent-facing, one-shot retrieval command: it runs the full intent-rewrite pipeline, runQueryTruthRetrieval, and enrichReadDocumentsAnswerWithLLM in a single pass. It is designed for programmatic use — agents (Claude Code, Cursor, Codex) call it to get a complete answer they can act on immediately. Chat mode is the user-facing, iterative experience: it uses executeChatQueryTruthRetrieval with auto-deepening, live in-memory message history, and conversational turn resolution across multiple back-and-forth exchanges. The two paths are intentionally different and should not be collapsed — query is for machines needing a deterministic answer, chat is for humans building understanding over time. — fact://c2bd509a11e0ca2f
    • CLI wording should make this explicit: these are knowledge-base cleanup operations, not codebase refactors. — fact://5c1acfe883057f35
    • Source code, tests, and unrelated repo assets are out of scope unless a separate code-editing command explicitly owns that responsibility. — fact://d30ad245d3660a52
    • Scope must be limited to the active KB store, not arbitrary repo files. — fact://6f6e71a313457782
  • For KB maintenance tools that mutate stored knowledge (for example invalidate_fact / kb invalidate): — fact://b9b297900918b63b
    • Examples exist for common use cases — fact://3f3dcbb43d235ab2
  • This means a query for “KbGraphWriter” can still surface facts that mention “SQLite” or “property graph” if those edges exist in the graph — even when the literal query string did not include those words. — fact://147979da16325171
  • The expanded term set is capped and concatenated to the original query for fact retrieval. — fact://c6d9430a60abd141
  • For every live edge touching those entities, expansion adds semantic triplets as natural-language phrases (Subject <predicate phrase> Object, plus the stored predicate slug and a spaced variant, e.g. — fact://ce5bc9af5d2198f3
    • weight: 1.0 for live edges, 0 for soft-deleted edges (set by kb invalidate) — fact://13573a3c8a36465a
    • type on relationships: canonical extractor labels (depends_on, contradicts, related_to, replaces, implements, uses) or any snake_case label you set via kb graph edge add --verb (free text is normalized to snake_case for storage) — fact://597b6f9d78afadf0
  • Graph tables live in <base-dir>/.kb-index.sqlite (kb_graph_entities, kb_graph_relationships), alongside documents, chunks, and facts. — fact://23c53c80ec0ef2a6
  • Session override: Pass --base <name> on kb graph (same as other KB commands) to target a specific session without switching your active base. — fact://e1581d19940acab2
  • Export: The full graph can be dumped as Graphviz DOT (for visualisation tools like Gephi or Mermaid) or JSON (for your own analysis). — fact://4c1f106d8b475c1a
  • As you build up your knowledge base, the graph gives you a structural view of how ideas connect — something the flat SQLite full-text index cannot express. — fact://ab58de76fc696b75
  • Your single responsibility is to execute the given instruction and report results clearly. — fact://c6c17d89fd705933
    • Your tool access is intentionally limited. — fact://a1c152ed55b7852c
    • The parent agent will integrate your output into a larger result. — fact://a1e1d4415244387e
  • You expand short or vague knowledge-base queries into targeted sub-queries. — fact://3447bc2f075af706