knowledge-base

This server is how an agent builds and maintains the knowledge graph: create and manage workspaces, ingest files, text, and URLs, keep the root mirror of your documents tree in sync, and enrich documents into entities and relationships. It is one of two arms over the same graph — this one writes and manages; its sibling arcadedb is the query arm agents read with.

The server itself is a thin front: all 22 kb_* tools forward to the knowledge-base daemon, the standalone local service that owns the graph work. That split is operationally useful — you can restart the knowledge layer from Dashboard ▸ Platform Health without touching your agent sessions, and if the daemon is stopped a tool call returns a clean "daemon unreachable" result instead of failing the session. The Cortex view drives the very same daemon, so what an agent ingests and what you see on the canvas can never drift apart.

The standout capability is zero-cost enrichment: kb_register_document plus kb_commit_entities let an agent read a document, extract entities and relationships in its own reasoning, and commit them to the graph — no external extraction service, no per-document API cost. Vector ingest (full depth) is the deliberate, opt-in exception for collections that earn semantic search.

How your agents use it

• "Make a workspace from this research folder." The agent calls kb_workspace_create, then kb_ingest_file per document — at structure depth this registers folders and documents in the graph with zero model calls.
• "Enrich those documents into the graph." The agent (or the dedicated ingester agent the Cortex Enrich action dispatches) reads each file and calls kb_register_document + kb_commit_entities — entities and relationships land in the graph at no external cost.
• "Is the root mirror current?" kb_sync_root refreshes the mirror of your documents tree; kb_root_stats reports its state; kb_search answers content questions — vector retrieval on full-depth workspaces, a ranked document search everywhere else.

Prerequisites

The knowledge-base daemon and the graph database must be running — both are managed in the app (Dashboard ▸ Platform Health and Settings ▸ Database; see the configuration reference). Structure and entities depths need no model key at all; full-depth ingest and vector search use your Gemini API key.

Tool reference

Tool	Parameters	What it does
kb_search	query*: string, mode: string, top_k: integer, workspace: string	VECTOR / HYBRID SEARCH — the vector arm of the unified workspace graph. MODE-AWARE by workspace DEPTH: on a `full`-depth workspace it runs hybrid vector + knowledge-graph retrieval and returns the most relevant passages; on a structure/entities workspace (no vectors — e.g. the default `_root`) it has no vector index, so it degrades to a knowledge-graph DOCUMENT search (ranked Document vertices) instead of erroring — there it OVERLAPS graph_find_documents, so on a non-`full` workspace prefer graph_find_documents directly. mode options (only used for `full` workspaces): 'mix' (KG + vector chunks, most comprehensive), 'hybrid' (KG local+global, recommended default), 'local' (entity-focused), 'global' (thematic), 'naive' (pure vector), 'bypass' (direct LLM, no retrieval). For GRAPH search (structure / entity / traversal — works at ANY depth) use the arcadedb graph_* tools: graph_find_documents (find docs by topic), graph_query_nl (natural-language → relevant subgraph), graph_query (raw SQL).
kb_ingest_file	path*: string, workspace: string, ingest_mode: string	Ingest a local file into a workspace's knowledge graph. Supports: PDF, DOCX, PPTX, HTML, XLSX, MD, TXT, RST, and code files (Python, TypeScript, Go, Rust, etc.). Provide the absolute file path. ingest_mode: 'graph_only' (default — entity extraction + KG, no embedding cost) or 'full' (KG + vector embeddings for semantic search).
kb_ingest_text	content*: string, title: string, workspace: string, ingest_mode: string	Ingest raw text or markdown content directly into a workspace. Use this to save findings, notes, or generated content.
kb_ingest_url	url*: string, workspace: string, ingest_mode: string	Fetch a URL and ingest its content into a workspace. Converts HTML to markdown before ingestion.
kb_edit	title*: string, new_content*: string, doc_id: string, workspace: string	Replace existing content in a workspace. Provide doc_id (from kb_list) to delete the old version before reinserting — this is a true replace. Without doc_id, the new content is appended and the old version remains in the index.
kb_delete	doc_id*: string, workspace: string	Delete a document from a workspace by its document ID.
kb_list	limit: integer, workspace: string	List recently ingested documents in a workspace.
kb_log_entry	action*: string, subject: string, workspace: string, details*: string	Append a LogEntry vertex to the knowledge graph timeline. Use this to record a custom analytical insight, a decision, or a cross-session finding that should appear in the Cortex Log view later. Ingest/delete/lint already log automatically.
kb_register_document	path*: string, workspace*: string, title: string	Register a document in the knowledge graph WITHOUT running any LLM extraction. Creates Folder / Document / CONTAINS / CHILD_OF vertices and edges, and ensures the workspace exists. Use this as the first step of a Claude-native ingest flow: call kb_register_document, then extract entities in your own reasoning context, then call kb_commit_entities to write them. Entirely Gemini-free.
kb_sync_root	—	Sync the holistic root knowledge graph. Walks documents/ recursively and upserts Folder + Document vertices into the reserved `_root` workspace without reading any file content — a pure structural mirror (structure depth). Runs in seconds for hundreds of files. Idempotent: re-running is safe. A sub-workspace ingest (a kb/general/named-root/artifact built from the same files) upgrades these structure-depth Document vertices in-place by appending its workspace name to the `workspaces` array.
kb_reset_root	—	Reset the holistic `_root` knowledge graph: clear ALL of `_root`'s graph data (the structure mirror + the opt-in entity layer) WITHOUT deregistering the reserved `_root` workspace, so a subsequent kb_sync_root rebuilds it from scratch. Drops graph + vector data ONLY — source files on disk are never touched. Vertices shared with sub-workspaces (a kb/general/named-root/artifact built from the same files) keep those memberships and survive; only `_root`-exclusive vertices are deleted. Irreversible (re-runnable via Sync). Returns updated/deleted counts + dropped entity types + errors.
kb_root_stats	—	Return folder/document counts and the most recent sync timestamp for the holistic `_root` workspace.
kb_root_config_get	—	Get the current root sync config: root_paths (list of directories to walk), include_exts, exclude_segments, max_size_bytes. Used by the Cortex Configure dialog to show the current state.
kb_root_config_update	root_paths: array, include_exts: array, exclude_segments: array, max_size_bytes: integer, reset: boolean	Update the root sync config. Partial updates are merged with the existing persisted config — pass only the keys you want to change. Pass `reset=true` to delete the persisted config and return to defaults. Validates structure before saving. Does NOT trigger a sync — caller must separately call kb_sync_root to apply.
kb_delete_folder	folder_path*: string	Delete a Folder vertex + all contained Document vertices + their incident CONTAINS / CHILD_OF / MENTIONS edges from the knowledge graph. Called when a real filesystem folder is removed and the KG should drop the corresponding subgraph. Does NOT touch the filesystem — caller handles the real folder removal separately.
kb_relocate_document	old_path*: string, new_path*: string	Update a Document vertex when a file has been moved or renamed. Updates path + folder_path + name fields and repoints CONTAINS edges to the new parent folder. Creates the new folder chain if it doesn't exist yet. Does NOT touch the filesystem — caller handles the real file move separately.
kb_workspace_create	name*: string, kg_depth: string, mode: string, type: string, source: object, description: string, parent: string, tags: array, icon: string	Create a new workspace in the registry. `type`: 'kb' (surfaced as a 'Knowledge Base'), 'general' (the SAME capability with no preset label — lives in the Cortex Workspaces tab), or a named 'root' (a folder-bound holistic mirror — pass `source.folder`). The capability axis is DEPTH — pass `kg_depth`: 'structure' (folders + documents, zero LLM), 'entities' (Claude-native entity extraction, no Gemini), or 'full' (entities + Gemini vector embeddings — enables vector kb_search). The legacy 'virtual'/'container' types are deprecated and rejected; 'artifact' workspaces are managed via ContextView KG mode — not created here. Storage mode is sticky after the first ingest.
kb_workspace_update	name*: string, description: string, parent: string, tags: array, icon: string	Update metadata on an existing workspace. Name, type, and mode are immutable — only description, parent, tags, icon can be changed.
kb_workspace_delete	name*: string, delete_source: boolean, drop_arcadedb: boolean	Delete a workspace from the registry + filesystem. Refuses if the workspace has children. Optionally also deletes the source folder and drops ArcadeDB types.
kb_workspace_list	type_filter: string, parent_filter: string	List all registered workspaces with full metadata + filesystem status. Optionally filter by type or parent.
kb_workspace_get	name*: string	Get full metadata + stats for a single workspace by name.
kb_commit_entities	workspace*: string, doc_path*: string, entities*: array, relationships: array, doc_description: string, doc_summary: string	Commit pre-extracted entities + relationships to a workspace knowledge graph. Entity vertices are upserted on entity_id (unique). MENTIONS edges are created from the Document vertex (must already exist via kb_register_document) to each entity. DIRECTED edges are created between entity pairs for each relationship. Entirely Gemini-free. Expected format: entities: [{entity_id, entity_type, description, keywords}] relationships: [{source, target, description, keywords, weight}] source and target in relationships must match entity_id values in the entities array (or already exist in the workspace).

Where to go next

• Knowledge graph — the full operating reference: depths, ingest paths, sync, lint
• Cortex — the human surface over the same graph
• Knowledge Base — curating document collections in the app
• arcadedb — the query arm over the same graph