Skip to content

BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.

Configure search through the TUI

Christian552fb720a980
diff --git a/tui/README.md b/tui/README.md
index 5cd5072..b1bda70 100644
--- a/tui/README.md
+++ b/tui/README.md
@@ -93,9 +93,10 @@ The interactive flow asks:
2. Otherwise: Vector DB → Data DB → Graph DB → Models mode
3. For `remote` models mode: pick provider, then provide GCP credentials, project, and model names
4. For `local` models mode: probe Ollama, wait for it to start, then verify pulled models
-5. Connection details for only the services you actually selected
-6. `BRAINPAT_TOKEN` (generate or paste)
-7. Optionally start the docker compose containers now
+5. Search: enable `/retrieve/search`? If yes, retrieval = both fused (default) / dense only / BM25 only. Requires `DATA_DB=postgresql`. Search p50 SLO is < 200 ms excluding embed RTT.
+6. Connection details for only the services you actually selected
+7. `BRAINPAT_TOKEN` (generate or paste)
+8. Optionally start the docker compose containers now
If Python (>=3.11) or Docker is missing, the TUI walks you through installing them with platform-aware commands and retries detection automatically.
diff --git a/tui/src/commands/config.ts b/tui/src/commands/config.ts
index bb1c151..9feb22e 100644
--- a/tui/src/commands/config.ts
+++ b/tui/src/commands/config.ts
@@ -11,6 +11,7 @@ import {
} from "../flows/pipeline.js";
import { askConnections } from "../flows/connections.js";
import { askAuth } from "../flows/auth.js";
+import { askSearch } from "../flows/search.js";
import { askServicesRuntime } from "../flows/services-runtime.js";
import {
runSetupWizard,
@@ -37,6 +38,7 @@ type ConfigMenuSection =
| "runtime"
| "models"
| "pipeline"
+ | "search"
| "connections"
| "auth"
| "plugins"
@@ -66,6 +68,15 @@ function draftSummary(draft: ConfigDraft): string {
? `Pipeline OCR: ${draft.pipeline.ocrMode}`
: "Pipeline OCR: not configured",
);
+ if (draft.search) {
+ lines.push(
+ draft.search.enabled
+ ? `Search: enabled (${draft.search.retrieval})`
+ : "Search: disabled",
+ );
+ } else {
+ lines.push("Search: not configured (default off)");
+ }
lines.push(
draft.connections ? "Connections: configured" : "Connections: not configured",
);
@@ -100,6 +111,7 @@ async function configMainMenu(): Promise<ConfigMenuSection> {
{ value: "runtime", label: "Services runtime" },
{ value: "models", label: "Models (LLM & embeddings)" },
{ value: "pipeline", label: "Pipeline (OCR)" },
+ { value: "search", label: "Search (BM25 + dense)" },
{ value: "connections", label: "Connection details" },
{ value: "auth", label: "Authentication token" },
{ value: "plugins", label: "Plugins (install/uninstall)" },
@@ -190,6 +202,20 @@ async function configurePipeline(draft: ConfigDraft): Promise<void> {
p.log.success("Pipeline updated.");
}
+async function configureSearch(draft: ConfigDraft): Promise<void> {
+ const search = await askSearch({
+ allowBack: true,
+ backHint: MENU_BACK_HINT,
+ initial: draft.search,
+ dataDb: draft.dbs?.dataDb,
+ });
+ if (isPromptBack(search)) {
+ return;
+ }
+ draft.search = search;
+ p.log.success("Search updated.");
+}
+
async function configureConnections(draft: ConfigDraft): Promise<void> {
if (!draft.dbs) {
p.log.warn("Configure databases first.");
@@ -393,6 +419,9 @@ export async function runConfig(): Promise<void> {
case "pipeline":
await configurePipeline(draft);
break;
+ case "search":
+ await configureSearch(draft);
+ break;
case "connections":
await configureConnections(draft);
break;
diff --git a/tui/src/constants.ts b/tui/src/constants.ts
index f0313d5..e3ebcb6 100644
--- a/tui/src/constants.ts
+++ b/tui/src/constants.ts
@@ -236,6 +236,14 @@ export const ENV_KEYS = {
embeddingDataDimension: "EMBEDDING_DATA_DIMENSION",
embeddingRelationshipsDimension: "EMBEDDING_RELATIONSHIPS_DIMENSION",
enabledPlugins: "ENABLED_PLUGINS",
+ searchEnabled: "SEARCH_ENABLED",
+ searchUseDense: "SEARCH_USE_DENSE",
+ searchUseBm25: "SEARCH_USE_BM25",
+ searchFusion: "SEARCH_FUSION",
+ searchFusionAlpha: "SEARCH_FUSION_ALPHA",
+ searchBm25K1: "SEARCH_BM25_K1",
+ searchBm25B: "SEARCH_BM25_B",
+ contextPassageMode: "CONTEXT_PASSAGE_MODE",
} as const;
export const SERVICE_COMPOSE_FILES = {
diff --git a/tui/src/flows/search.ts b/tui/src/flows/search.ts
new file mode 100644
index 0000000..ba6b453
--- /dev/null
+++ b/tui/src/flows/search.ts
@@ -0,0 +1,117 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { isPromptBack, pickOne, type PromptBack } from "../lib/prompts.js";
+import type { SearchChoices, SearchRetrieval } from "../types.js";
+
+const DEFAULT_SEARCH: SearchChoices = {
+ enabled: false,
+ retrieval: "hybrid",
+};
+
+export function defaultSearchChoices(): SearchChoices {
+ return { ...DEFAULT_SEARCH };
+}
+
+export async function askSearch(options?: {
+ allowBack?: false;
+ initial?: SearchChoices;
+ dataDb?: string;
+}): Promise<SearchChoices>;
+export async function askSearch(options: {
+ allowBack: true;
+ backHint?: string;
+ initial?: SearchChoices;
+ dataDb?: string;
+}): Promise<SearchChoices | PromptBack>;
+export async function askSearch(options?: {
+ allowBack?: boolean;
+ backHint?: string;
+ initial?: SearchChoices;
+ dataDb?: string;
+}): Promise<SearchChoices | PromptBack> {
+ p.log.step("Search");
+ if (options?.dataDb && options.dataDb !== "postgresql") {
+ p.log.info(
+ pc.dim(
+ "Hybrid search needs DATA_DB=postgresql. Leaving SEARCH_ENABLED=false.",
+ ),
+ );
+ return { enabled: false, retrieval: "hybrid" };
+ }
+
+ const enabledChoice = options?.allowBack
+ ? await pickOne<"yes" | "no">({
+ message: "Enable hybrid search API (/retrieve/search)?",
+ options: [
+ {
+ value: "no",
+ label: "No (default)",
+ hint: "memory path unchanged; search routes return 404",
+ },
+ {
+ value: "yes",
+ label: "Yes",
+ hint: "BM25 + dense ANN; fused by default; p50 < 200 ms ex-embed",
+ },
+ ],
+ initialValue: options.initial?.enabled ? "yes" : "no",
+ allowBack: true,
+ backHint: options.backHint,
+ })
+ : await pickOne<"yes" | "no">({
+ message: "Enable hybrid search API (/retrieve/search)?",
+ options: [
+ {
+ value: "no",
+ label: "No (default)",
+ hint: "memory path unchanged; search routes return 404",
+ },
+ {
+ value: "yes",
+ label: "Yes",
+ hint: "BM25 + dense ANN; fused by default; p50 < 200 ms ex-embed",
+ },
+ ],
+ initialValue: options?.initial?.enabled ? "yes" : "no",
+ });
+ if (isPromptBack(enabledChoice)) {
+ return enabledChoice;
+ }
+ if (enabledChoice === "no") {
+ return { enabled: false, retrieval: "hybrid" };
+ }
+
+ const retrieval = options?.allowBack
+ ? await pickOne<SearchRetrieval>({
+ message: "Search retrieval",
+ options: [
+ {
+ value: "hybrid",
+ label: "Both fused (default)",
+ hint: "parallel BM25 ∪ dense, RRF",
+ },
+ { value: "dense", label: "Dense only" },
+ { value: "bm25", label: "BM25 only" },
+ ],
+ initialValue: options.initial?.retrieval ?? "hybrid",
+ allowBack: true,
+ backHint: options.backHint,
+ })
+ : await pickOne<SearchRetrieval>({
+ message: "Search retrieval",
+ options: [
+ {
+ value: "hybrid",
+ label: "Both fused (default)",
+ hint: "parallel BM25 ∪ dense, RRF",
+ },
+ { value: "dense", label: "Dense only" },
+ { value: "bm25", label: "BM25 only" },
+ ],
+ initialValue: options?.initial?.retrieval ?? "hybrid",
+ });
+ if (isPromptBack(retrieval)) {
+ return retrieval;
+ }
+ return { enabled: true, retrieval };
+}
diff --git a/tui/src/flows/setup-wizard.ts b/tui/src/flows/setup-wizard.ts
index e54993d..cd5d63f 100644
--- a/tui/src/flows/setup-wizard.ts
+++ b/tui/src/flows/setup-wizard.ts
@@ -3,6 +3,7 @@ import { askUseDefaults, DEFAULT_DBS } from "./defaults.js";
import { askDatabases } from "./services.js";
import { askModels } from "./models.js";
import { askPipeline } from "./pipeline.js";
+import { askSearch, defaultSearchChoices } from "./search.js";
import { askConnections } from "./connections.js";
import { askAuth } from "./auth.js";
import { askServicesRuntime } from "./services-runtime.js";
@@ -20,6 +21,7 @@ import type {
ModelsChoices,
PluginChoice,
PipelineChoices,
+ SearchChoices,
ServicesRuntime,
} from "../types.js";
@@ -28,6 +30,7 @@ export interface SetupDraft {
servicesRuntime?: ServicesRuntime;
models?: ModelsChoices;
pipeline?: PipelineChoices;
+ search?: SearchChoices;
connections?: Connections;
auth?: AuthChoices;
plugins?: PluginChoice[];
@@ -47,6 +50,7 @@ export function toInitChoices(draft: SetupDraft): InitChoices {
servicesRuntime: draft.servicesRuntime!,
models: draft.models!,
pipeline: draft.pipeline!,
+ search: draft.search ?? defaultSearchChoices(),
connections: draft.connections!,
auth: draft.auth!,
plugins: draft.plugins ?? [],
@@ -243,19 +247,35 @@ export async function runSetupWizard(
}
if (step === 5) {
+ const search = await askSearch({
+ allowBack: true,
+ backHint: stepBackHint,
+ initial: draft.search,
+ dataDb: draft.dbs?.dataDb,
+ });
+ if (isPromptBack(search)) {
+ step = draft.usedDefaults ? 3 : 4;
+ continue;
+ }
+ draft.search = search;
+ step = 6;
+ continue;
+ }
+
+ if (step === 6) {
if (!draft.dbs) {
step = draft.usedDefaults ? 0 : 1;
continue;
}
draft.connections = await askConnections(draft.dbs, flags);
- step = 6;
+ step = 7;
continue;
}
- if (step === 6) {
+ if (step === 7) {
if (flags?.brainpatToken) {
draft.auth = { brainpatToken: flags.brainpatToken };
- step = 7;
+ step = 8;
continue;
}
const auth = await askAuth({
@@ -264,15 +284,15 @@ export async function runSetupWizard(
prechosenToken: flags?.brainpatToken,
});
if (isPromptBack(auth)) {
- step = 5;
+ step = 6;
continue;
}
draft.auth = auth;
- step = 7;
+ step = 8;
continue;
}
- if (step === 7) {
+ if (step === 8) {
if (flags?.noPlugins || flags?.plugins !== undefined) {
draft.plugins = flags.noPlugins ? [] : (flags.plugins ?? []);
return true;
@@ -285,7 +305,7 @@ export async function runSetupWizard(
skip: flags?.noPlugins,
});
if (isPromptBack(plugins)) {
- step = 6;
+ step = 7;
continue;
}
draft.plugins = plugins;
diff --git a/tui/src/lib/write-env.ts b/tui/src/lib/write-env.ts
index b49fb9b..216137e 100644
--- a/tui/src/lib/write-env.ts
+++ b/tui/src/lib/write-env.ts
@@ -65,6 +65,8 @@ export async function writeEnvFromChoices(choices: InitChoices): Promise<void> {
values[ENV_KEYS.runGraphConsolidator] = "true";
values[ENV_KEYS.celeryWorkerConcurrency] = 4;
+ applySearchValues(values, choices);
+
values[ENV_KEYS.brainpatToken] = choices.auth.brainpatToken;
values[ENV_KEYS.enabledPlugins] = choices.plugins.map((plugin) => plugin.name).join(",");
values["ENV"] = "development";
@@ -85,6 +87,25 @@ export async function writeEnvFromChoices(choices: InitChoices): Promise<void> {
await saveEnv(env);
}
+function applySearchValues(
+ values: Record<string, string | number | undefined>,
+ choices: InitChoices,
+): void {
+ const search = choices.search ?? { enabled: false, retrieval: "hybrid" };
+ const enabled = search.enabled;
+ const retrieval = search.retrieval ?? "hybrid";
+ values[ENV_KEYS.searchEnabled] = enabled ? "true" : "false";
+ values[ENV_KEYS.searchUseDense] =
+ !enabled || retrieval === "hybrid" || retrieval === "dense" ? "true" : "false";
+ values[ENV_KEYS.searchUseBm25] =
+ !enabled || retrieval === "hybrid" || retrieval === "bm25" ? "true" : "false";
+ values[ENV_KEYS.searchFusion] = "rrf";
+ values[ENV_KEYS.searchFusionAlpha] = "0.5";
+ values[ENV_KEYS.searchBm25K1] = "1.2";
+ values[ENV_KEYS.searchBm25B] = "0.75";
+ values[ENV_KEYS.contextPassageMode] = enabled ? "hybrid" : "hybrid";
+}
+
function applyPostgresValues(
values: Record<string, string | number | undefined>,
choices: InitChoices,
diff --git a/tui/src/types.ts b/tui/src/types.ts
index 987a334..9d7dabc 100644
--- a/tui/src/types.ts
+++ b/tui/src/types.ts
@@ -12,6 +12,7 @@ export type ModelProvider =
| "amazon_bedrock";
export type OcrMode = "docparser" | "docling";
export type PipelineMode = "accurate" | "lightweight";
+export type SearchRetrieval = "hybrid" | "dense" | "bm25";
export type ServicesRuntime = "docker" | "manual";
export type PluginSource = "local" | "registry";
@@ -156,6 +157,11 @@ export interface PipelineChoices {
ocrMode: OcrMode;
}
+export interface SearchChoices {
+ enabled: boolean;
+ retrieval: SearchRetrieval;
+}
+
export interface PluginChoice {
name: string;
source: PluginSource;
@@ -167,6 +173,7 @@ export interface InitChoices {
dbs: DbChoices;
models: ModelsChoices;
pipeline: PipelineChoices;
+ search: SearchChoices;
connections: Connections;
auth: AuthChoices;
plugins: PluginChoice[];