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.2,<0.3), 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.
textclean Outside text made safe to hand to a model: invisible and bidirectional characters removed, HTML reduced to the text a reader sees (hidden text dropped), and outside_text_notice, the sentence an answer carrying such text puts first.
testing Security regression checks each server runs against itself in its own CI, including check_no_invisible_characters over its own source.
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.2.0

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.2.0
File Size Uploaded Provenance Actions
second_brain_core-0.2.0.tar.gz 457.3 kB With provenance Details for second_brain_core-0.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 521.6 kB

Release files / second_brain_core-0.2.0.tar.gz

Download URL second_brain_core-0.2.0.tar.gz
Size 457.3 kB
Tags Source
SHA-256 checksum
How to use checksums
36a0a05c7ebc4a1595e2cff88c52f8b5b77e533db5736db9b7d57f1d852b4b14
BLAKE2b-256 checksum
How to use checksums
20921b77277e1202ff06cbe27c37757079ae18f1b0a636f3c1e9f0d889f3ffad
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.2.0-py3-none-any.whl

Download URL second_brain_core-0.2.0-py3-none-any.whl
Size 64.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
284c70f9bbb510870ebee5b6dfb9d9f6812c22a2e4882c3c3d656abdfab72143
BLAKE2b-256 checksum
How to use checksums
575872c9c4cf6edb3c0db132ed32353a0916a0b03e5678196ade059026e34b3c
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.2.0

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.2.0.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