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.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.1.0
File Size Uploaded Provenance Actions
second_brain_core-0.1.0.tar.gz 441.6 kB With provenance Details for second_brain_core-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 496.7 kB

Release files / second_brain_core-0.1.0.tar.gz

Download URL second_brain_core-0.1.0.tar.gz
Size 441.6 kB
Tags Source
SHA-256 checksum
How to use checksums
82fd3881c2660ec8c2d0cc30741eb4711112c9da731f23343d011bfff2fb7dce
BLAKE2b-256 checksum
How to use checksums
a1728a083a83a96d9914e83e55669391a0d4418a3df5a4fdf42d5bb1e68e4ad7
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.0-py3-none-any.whl

Download URL second_brain_core-0.1.0-py3-none-any.whl
Size 55.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f2c0fcbf87889aaaeaeca07153ad64cbbb3f84609210e1c1e717bf4227e6e781
BLAKE2b-256 checksum
How to use checksums
66d5a5478a878af3934a6142fad0a0d78cbb51d8e5af12ca8f7a5c942a3d5c8e
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.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.1.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