Superbrain Lt

Superbrain Light

Superbrain Light is a Rust MCP server that stores conversation turns, extracts atomic memories, and searches sessions and memories with PostgreSQL full-text and vector retrieval. It can also ingest local Markdown files into searchable file-backed sessions.

The project vocabulary is:

• Domain: top-level namespace for a group of sessions.
• Sub-Domain: optional second-level namespace inside a domain.
• Session: durable conversation, work stream, or ingested file.
• Turn: one ordered source message or file chunk in a session.
• Memory: extracted atomic fact linked back to source turns.

Features

• MCP server over stdio or Streamable HTTP.
• Automatic database migrations at startup and before file-ingestion scans.
• Session and turn persistence with per-session ordering.
• Synchronous memory extraction when turns are added or replaced.
• openai-codex-oauth and openai-api extraction providers.
• openai-oauth-embeddings embeddings for semantic search.
• Hybrid, vector, and full-text search for sessions and memories.
• Recent session and memory listing with domain, sub-domain, and tag filters.
• Markdown file ingestion through one-shot CLI scans or opt-in periodic scans.
• Hard-delete tools for sessions and individual memories.

MCP Tools

Superbrain Light exposes nine MCP tools:

add_turns accepts 1 to 20 turns per call. Turn roles are user, assistant, tool, system, and note. Use create_mode values create_or_append (default), create_only, or append_only; appending to an existing session requires the latest updated_at as expected_updated_at. Stale write preconditions return an MCP conflict (-32009). Search tools accept mode values of hybrid, vector, or fts, and limit values from 1 to 100.

Prerequisites

• Rust stable with rustfmt and clippy; the pinned toolchain is in rust-toolchain.toml.
• PostgreSQL with pgvector and pgcrypto available.
• A database role that can run the bundled migrations on first startup.
• OpenAI OAuth tokens for embeddings. Extraction can use either OAuth tokens or an API key, but serve mode always builds the OAuth-backed embedder.

Install

Build the binary:

cargo build --release

Install it from this checkout:

cargo install --path . --locked

Create a database:

createdb superbrain_light
export DATABASE_URL=postgres://localhost/superbrain_light

Startup applies the migrations in migrations/. The target database must be able to create the vector and pgcrypto extensions, or those extensions must already exist.

Runtime Configuration

DATABASE_URL takes precedence over --database-url when both are set.

Provider Configuration

Provider configuration is read from SUPERBRAIN_LIGHT_CONFIG, or ./superbrain-light.toml when the environment variable is unset. A starting point ships as superbrain-light.toml.example; copy it to superbrain-light.toml and adjust as needed.

extraction.system_prompt_file is required — there is no extraction prompt built into the binary. Point it at an extraction prompt file; the repository ships prompts/engineering-memory-extraction.md. Relative paths are resolved from the config file directory. The server refuses to start if the value is unset or the file cannot be read.

[extraction]
name = "openai-codex-oauth"
system_prompt_file = "prompts/engineering-memory-extraction.md"

[embedding]
name = "openai-oauth-embeddings"

Use openai-api when extraction should use an API key. Embeddings still use stored OAuth tokens.

[extraction]
name = "openai-api"
system_prompt_file = "prompts/engineering-memory-extraction.md"

[extraction."openai-api"]
api_key_env = "OPENAI_API_KEY"
model = "gpt-5.4-mini"
temperature = 0.2
max_output_tokens = 1000
top_p = 0.8
reasoning_effort = "low"
store = false
base_url = "https://api.openai.com/v1"

[embedding]
name = "openai-oauth-embeddings"

Relative system_prompt_file paths are resolved from the config file directory. openai-api accepts reasoning_effort values minimal, low, medium, and high. base_url must be HTTPS except for localhost test endpoints.

Run

First startup needs OAuth tokens for embeddings. The bootstrap file can use flat access_token / refresh_token fields or a nested tokens object:

export DATABASE_URL=postgres://localhost/superbrain_light
export SUPERBRAIN_LIGHT_BOOTSTRAP_AUTH=/path/to/auth.json

superbrain-light \
  --database-url "$DATABASE_URL" \
  --bootstrap-from "$SUPERBRAIN_LIGHT_BOOTSTRAP_AUTH"

After tokens are stored in the database, future starts can omit --bootstrap-from unless the tokens need to be replaced.

Run Streamable HTTP instead of stdio:

superbrain-light \
  --database-url "$DATABASE_URL" \
  --bootstrap-from "$SUPERBRAIN_LIGHT_BOOTSTRAP_AUTH" \
  --listen 127.0.0.1:3000

The Streamable HTTP endpoint is http://127.0.0.1:3000/mcp.

To store and search turns without creating memories, start with --disable-extraction or set SUPERBRAIN_LIGHT_DISABLE_EXTRACTION=true. Embeddings remain enabled, so OAuth tokens are still required. In this mode add_turns returns memory_count: 0 and memory_ids: [].

For local development without installing the binary:

cargo run -- \
  --database-url "$DATABASE_URL" \
  --bootstrap-from "$SUPERBRAIN_LIGHT_BOOTSTRAP_AUTH" \
  --listen 127.0.0.1:3000

File Ingestion

File ingestion reads [[ingest]] blocks from the same TOML file as provider configuration. Only Markdown files with a supported .md extension are indexed. Relative root_path values are resolved from the config file directory.

scan_interval_seconds = 0

[[ingest]]
domain = "docs"
root_path = "./docs"
include_globs = ["**/*.md"]
exclude_globs = ["**/.git/**", "**/target/**"]
settle_seconds = 10
max_heading_split_level = 2
chunk_size_chars = 4000
chunk_overlap_chars = 200
tags = ["kind:docs"]

Run a one-shot scan:

superbrain-light --database-url "$DATABASE_URL" ingest scan

Useful scan flags:

In serve mode, set scan_interval_seconds above 0 and define at least one [[ingest]] block to enable periodic scans. The first scan starts immediately, then repeats at the configured interval.

Ingested files are stored as sessions in the configured domain and sub_domain: "FILES". Each chunk is a note turn. File ingestion does not create memories. File sessions receive kind:file, ext:<ext>, and any configured root tags, so callers can find them with search_sessions.

Operations

The repository includes systemd unit templates under deploy/systemd/ for the MCP server and optional file-ingestion scans. Adjust paths, environment files, and service names for your environment.

Build And Test

Run the maintained verification gate:

scripts/verify-superbrain-light.sh

The core Rust checks are:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --workspace

Optional live end-to-end verification requires a disposable PostgreSQL database plus OpenAI credentials:

SUPERBRAIN_LIGHT_LIVE=1 scripts/verify-superbrain-light.sh --live

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License. A full copy of the License is provided in the LICENSE file and may also be obtained at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.