Skip to main content

second-brain-core

The shared library of the Second Brain MCP servers: second-brain-joplin (notes) and its sibling for mail. Each server talks to one store; everything they do the same way lives here, written and tested once.

0.x: the interfaces may still change. Each server pins a compatible range (second-brain-core>=0.1,<0.2), and a change that breaks one is a new minor version.

What it holds

Module What it does
server Server: how a server describes itself (its name, variable prefix, package, port). Every other piece takes it, so nothing here names a product.
env Where settings come from (the environment, then a named --env-file or a checkout's .env, never both), and readers that never raise.
auth GitHub sign-in for HTTP mode through FastMCP's OAuth proxy, limited to listed numeric GitHub ids.
audit One log line per tool call (tool, caller, client, outcome, duration; never arguments, results or tokens), the per-caller rate limit, and the logging set-up that keeps tokens and content out of the log.
remote HTTP mode's options, the start-up guardrails, the transport choice (stdio unless asked), the middleware stack, and the run calls.
health The /healthz route: two booleans, 503 when the store is down.
failure The error a client sees: a planned failure's own sentence, or a fixed one for anything unplanned.
recent A short memory of what a write answered, so a repeated request writes nothing new.
annotations The tool annotations every server uses the same way.
testing Security regression checks each server runs against itself in its own CI.
semantic The semantic extra: search by meaning, and by words, over a server's items. The server supplies a Source; the Engine keeps the index in step and searches it, returning only what the source says is visible now. Stores: sqlite-vec (the default, with an FTS5 word index) and Chroma. semantic.testing has in-memory stand-ins for tests.

Using it in a server

# my_server/__init__.py: import the library first, and nothing that imports fastmcp.
import second_brain_core  # noqa: F401  (pins FastMCP's env file before fastmcp loads)

# my_server/app.py
from second_brain_core.server import Server

SERVER = Server(name="my-server", prefix="SBM_", package="my_server", default_port=8777)

Importing second_brain_core must come before anything imports fastmcp. FastMCP reads its own settings, the transport among them, from a .env in the working directory when it is first imported; importing this package stops that. Keep the server's __init__.py free of other imports, because import sorting would move a fastmcp import above it. testing.check_dotenv_cannot_set_fastmcp catches the mistake; run it in the server's suite.

Then build the server with remote.build_middleware(SERVER, ...) and mask_error_details=True, end every tool with failure.tool_error for the failures it plans for and failure.unexpected for the rest, and serve with remote.run_stdio or remote.run_http.

Search by meaning

pip install "second-brain-core[semantic]"            # sqlite-vec + FastEmbed (the default)
pip install "second-brain-core[semantic,semantic-chroma]"   # the Chroma store
pip install "second-brain-core[semantic,semantic-st]"       # sentence-transformers models

A server re-exports these as its own extras. Each server keeps its own index directory: the index file records which server owns it and refuses another. The embedding runtime has no build for Python 3.15 yet, so the extra needs 3.11 to 3.14.

Releasing

The library is released first: a change a server needs is released here, then the server's pin moves to it. See docs/releasing.md.

License

GNU Affero General Public License, version 3 or later (LICENSE).

Metadata

Release files for second-brain-core 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for second-brain-core 0.1.1
File Size Uploaded Provenance Actions
second_brain_core-0.1.1.tar.gz 443.7 kB With provenance Details for second_brain_core-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for second-brain-core 0.1.1
File Interpreter ABI Platform Actions
second_brain_core-0.1.1-py3-none-any.whl Python 3 none any Details for second_brain_core-0.1.1-py3-none-any.whl

Total release size: 499.3 kB

Release files / second_brain_core-0.1.1.tar.gz

Download URL second_brain_core-0.1.1.tar.gz
Size 443.7 kB
Tags Source
SHA-256 checksum
How to use checksums
cb00309d1357be5ed4ef40fe5d5e2f638b562794beaac5329ed17c1431945409
BLAKE2b-256 checksum
How to use checksums
71e88ae77beac8605152dacb2d0a9fe999e30541961da3fa4af17b0cfe16ee3f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

Release files / second_brain_core-0.1.1-py3-none-any.whl

Download URL second_brain_core-0.1.1-py3-none-any.whl
Size 55.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d46ca3ba1e9727b1d01e4a79a8feaa0bb4f07044da343e43738177cc0b6288a4
BLAKE2b-256 checksum
How to use checksums
6413618e8065adb03aef3973211fec33070d710886dcacafed3b00e49941e75b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

Security for second-brain-core 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for second_brain_core-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page