Skip to content
AgentCTX

Knowledge Search

Knowledge Search

Section titled “Knowledge Search”

The knowledge plane lets agents search across your project’s documentation, code, and data files using full-text search with fuzzy prefix matching. This guide covers ingestion, searching, and best practices.

Ingesting Content

Section titled “Ingesting Content”

Via Configuration

Section titled “Via Configuration”

Configure knowledge sources in actx.yaml:

planes:
  knowledge:
    enabled: true
    sources: ["docs/", "src/"]

The filesystem watcher automatically indexes these directories and re-indexes when files change.

Via CLI

Section titled “Via CLI”
Terminal window
actx ingest docs/
actx ingest README.md

Via CTX

Section titled “Via CTX”
+k source="docs/api-reference.md"

Searching

Section titled “Searching”
Section titled “Basic Search”
?k "authentication patterns"

Returns matching chunks ranked by relevance score using fuzzy full-text search.

With Filters

Section titled “With Filters”
?k "authentication" #code @7d ^3
  • #code — only chunks tagged as code
  • @7d — indexed within the last 7 days
  • ^3 — return top 3 results

With Project Scope

Section titled “With Project Scope”
?k "deploy" *my-project

Scopes the search to a specific project namespace.

Exact Lookup

Section titled “Exact Lookup”
!k doc-abc123

Retrieves a specific document chunk by its ID.

How It Works

Section titled “How It Works”
  1. Chunking — documents are split into meaningful segments
  2. Indexing — chunks are indexed by MiniSearch across title, content, tags, and source fields
  3. Querying — ?k queries are matched using full-text search with fuzzy prefix matching (0.2 fuzziness)
  4. Filtering — results are filtered by CTX filters (#tag, *project)
  5. Ranking — results are ranked by MiniSearch relevance score and limited by ^N

Note: The SurrealDB schema defines HNSW vector indices for future use via the surrealqlNative dual-path. When surrealqlNative=true, queries route through SurrealDB’s HNSW nearest-neighbor search instead of MiniSearch. The TypeScript path (MiniSearch) is the current default.

Write Gate

Section titled “Write Gate”

Before storage, every chunk passes through a write gate that:

  • Deduplicates against existing content (content-addressed hashing)
  • Validates format and size
  • Prevents redundant storage

Best Practices

Section titled “Best Practices”
  1. Keep sources focused — index relevant directories, not your entire filesystem
  2. Use tags — categorize knowledge for precise retrieval
  3. Let the watcher work — configure sources in actx.yaml for automatic re-indexing
  4. Combine with memory — use knowledge for documents, memory for decisions and lessons
  5. Limit results — always use ^N to avoid overwhelming the agent’s context

See Also

Section titled “See Also”