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.
MCP memory-extraction server: extracts durable engineering memories from coding-session transcripts and serves them over hybrid search (Postgres + pgvector).
星标
2
工具
—
可用率
—
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:
Tool
Purpose
add_turns
Create or append ordered turns to a session and synchronously extract memories.
get_session
Fetch one session with turns and memory provenance.
update_session
Update session metadata and optionally replace ordered turns atomically.
get_recent_sessions
List recent sessions filtered by domain, sub-domain, and tags.
get_recent_memories
List recent memories filtered by session path and tags.
search_sessions
Search turns and return ranked sessions with inline turn_hits.
search_memories
Search extracted memories with source turn provenance.
delete_session
Hard-delete one session and cascade its turns and linked memories.
delete_memory
Hard-delete one memory by optimistic version.
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.
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.
Disable memory extraction while keeping embeddings, writes, and turn search enabled. Truthy env values are true, 1, yes, and on.
SUPERBRAIN_LIGHT_CONFIG
No
Provider and ingest TOML path. Defaults to ./superbrain-light.toml.
SUPERBRAIN_LIGHT_EXTRACTION_PROVIDER
No
Override extraction provider: openai-codex-oauth or openai-api.
SUPERBRAIN_LIGHT_EMBEDDING_PROVIDER
No
Override embedding provider. Current valid value: openai-oauth-embeddings.
RUST_LOG
No
Tracing filter, for example superbrain_light=info,tower_http=info.
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:
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:
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.
Preview changes without writing to the database or building embeddings.
--force
Bypass safety aborts and re-index unchanged files. Use after chunking config changes.
--no-embeddings
Store file turns with NULL embeddings for FTS-only search.
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.
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.
S
Superbrain Lt
endyii·2 个星标·
MCP memory-extraction server: extracts durable engineering memories from coding-session transcripts and serves them over hybrid search (Postgres + pgvector).
上次检查时间:2026-10-28。 MCP memory-extraction server: extracts durable engineering memories from coding-session transcripts and serves them over hybrid search (Postgres + pgvector).