second-brain MCP server
Commit Oct 28, 2026Provides a local-first knowledge graph for AI agents using Markdown files and SQLite to maintain persistent memory across different LLM clients.
Also known as stancsz/second-brain
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 28, 2026
- License
- MIT
What is second-brain MCP?
second-brain provides a local-first knowledge graph for AI agents using Markdown files and SQLite to maintain persistent memory across different LLM clients.
Summary generated from the project's README
About second-brain MCP server
Maintaining persistent memory across different AI agents is possible with this local-first knowledge graph. It allows developers to store architectural decisions, task progress, and concepts in a way that Claude, Codex, Gemini, OpenCode, and Cline can all access. Instead of relying on third-party hosted memory products, this system uses Markdown files as the source of truth, ensuring you own your data.
Users interact with the system through a command-line interface, an Agent Skill package, or a stdio MCP server. The core storage is an OKF-flavored Markdown Bundle, while a SQLite database serves as a replaceable search index. Because the data is stored as files, you can use Git for bidirectional synchronization or create immutable snapshots to local disks or cloud providers. No external accounts are required to run the Python core, and the system supports optional encryption via a Fernet backend.
What you can do with it
- 1Share memory across multiple agentsProvide a unified knowledge base so that switching from Claude to Gemini does not result in a loss of context.
- 2Track project task progressInstruct an agent to save a summary of accomplishments and remaining blockers before it finishes a task.
- 3Sync knowledge via GitUse version control to keep your agent's memory synchronized across different machines.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
SECONDBRAIN_POSTGRES_DSNSECONDBRAIN_REQUIRE_ENCRYPTION
| Name | Description | |
|---|---|---|
| SECONDBRAIN_POSTGRES_DSN | — | |
| SECONDBRAIN_REQUIRE_ENCRYPTION | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablestancsz/second-brain is public and reachablegithub.com/stancsz/second-brain ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-28github.com/stancsz/second-brain ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubsecond-brain
One memory for Claude, Codex, Gemini, OpenCode, and Cline — stored as files you own.
second-brain is a local-first knowledge graph for AI agents. Its canonical
store is an OKF-flavoured Markdown Bundle; SQLite is a disposable search index.
The same memory is available through an Agent Skill, a command-line interface,
and a stdio MCP server.
Beta, with evidence. The package, local engine, MCP subprocess, Obsidian format behaviour, snapshot/restore path, and 262-test suite are checked in. Live activation in every agent host and live cloud-provider accounts are not yet part of CI. See the compatibility matrix.
Why this exists
Ask one agent to remember an architectural decision, switch tools, and the next agent usually starts cold. Hosted memory products solve that by putting another vendor between you and your own history.
second-brain takes the opposite approach:
- Files are truth. Notes remain inspectable Markdown with stable IDs and wikilinks. Exported OKF Markdown uses LF line endings so synced Bundle diffs stay stable across platforms.
- Agents are clients. Claude, Codex, Gemini, OpenCode, and Cline share the same open skill package; MCP-capable clients can call the same brain over JSON-RPC. Host activation evidence is tracked explicitly below.
- Indexes are replaceable. Delete SQLite, rebuild it from the Bundle, and continue.
- Writes are paired. Supported CLI/MCP mutations flush Markdown before they report success; a lock, receipt, and crash journal refuse stale or mixed generations instead of guessing.
- Storage stays yours. Git handles bidirectional sync. Immutable snapshots can go to local disk, rclone providers, PostgreSQL, or Supabase.
- No account is required. The Python core uses the standard library.
Install the skill
Install one package for all five target hosts with the open Agent Skills installer:
npx skills add stancsz/second-brain \
--skill second-brain --global --copy -y \
--agent claude-code codex gemini-cli opencode cline
The installer accepts all five host names and the package validates locally and with the official Agent Skills validator. That proves installation/package compatibility—not native activation inside each host. Host application activation remains a manual smoke test until the project has a maintained host-version matrix.
In a Windows smoke using this exact command, the installer materialized copies
under .agents/skills/second-brain and .claude/skills/second-brain. That is
useful package-install evidence; it does not prove that Gemini CLI, OpenCode,
or Cline will discover the skill in their current native configuration.
The copied .agents skill was then run from its installed path in an isolated
home: add --json created a Concept and search --json retrieved it. This
proves the package remains executable after copying; it is still not a native
host handshake.
Prefer a plain clone, or only want the CLI?
git clone https://github.com/stancsz/second-brain.git
cd second-brain
python scripts/brain_cli.py add "Atlas storage decision" \
"Markdown is canonical; SQLite is rebuilt from it." \
--collection Decisions --tags atlas,architecture
python scripts/brain_cli.py search "Why SQLite?"
Install the Python CLI from a checkout or package index with pip install .;
this installs the brain command and has no third-party runtime dependencies.
To enable encryption, install the optional extra with pip install '.[encryption]'
(or pip install 'second-brain-cli[encryption]' after publication). The extra
installs the optional cryptography Fernet backend.
Data is created under ~/.secondbrain/. Use --db PATH to isolate a different
brain.
What works where
| Surface | Claude Code | Codex | Gemini CLI | OpenCode | Cline |
|---|---|---|---|---|---|
| Agent Skill package | package-validated | package-validated | documented target + MCP registration smoke | documented target + MCP registration smoke | documented target + MCP registration smoke |
| Local stdio MCP server | registration/health smoke on Claude Code 2.1.146 | registration smoke on Codex 0.87.0 | registration smoke on Gemini CLI 0.26.0 | registration smoke on OpenCode 1.15.10 | registration smoke on Cline 3.0.51 |
| Lifecycle hooks / task checkpoints | capture/recall tested | project Stop checkpoint; live handshake pending | — | — | — |
“Subprocess protocol-tested” means the repository launches the MCP subprocess
and exercises initialize, tools/list, brain_add, and brain_search in an
isolated home. The named registration smokes additionally exercise a host CLI
configuration parser; neither level proves a model-backed fresh-session
handshake. The evidence matrix separates repo tests,
package validation, parser smokes, and live-host gaps.
For host-specific skill paths, MCP configuration, and the fresh-session test,
see HOST_SETUP.md.
Run python scripts/host_matrix.py --json for a content-free package/MCP
readiness report covering all five named hosts. It marks native host launch as
a separate manual gate; it does not pretend that a repository test operated a
proprietary host UI.
Claude Code users can optionally install the included Stop, PreCompact, and
UserPromptSubmit hooks:
bash install.sh
The installer merges settings instead of replacing them. Review any lifecycle hook before enabling it; conversation capture is sensitive data.
Project task checkpoints
This repository includes AGENTS.md and CLAUDE.md instructions for saving a
concise Second Brain Work concept before an agent finishes substantive work.
The note records an estimated completion percentage, accomplishments,
remaining work or blockers, and verification status. Agents search for the same
task first and update its existing concept when there is a clear match. Raw
transcripts are never copied into the Brain.
Codex also reads the project hook configuration in .codex/hooks.json. Its
Stop and SubagentStop hooks ask the agent to complete the checkpoint before
finishing. Review and trust the project hook when Codex prompts. Other hosts
follow the project instructions when they load them, but do not inherit a
portable Stop hook; lifecycle hook APIs differ by host.
For host paths, MCP setup, and verification details, see Host setup and Compatibility.
Core workflow
Claude / Codex / Gemini / OpenCode / Cline
│
Agent Skill · MCP · CLI
│
OKF Markdown Bundle ← canonical
├── SQLite FTS index ← rebuildable
├── git history ← bidirectional sync
└── snapshots ← one-way restore mirrors
Useful commands:
# Capture and recall
python scripts/brain_cli.py add "Decision" "Use customer-owned storage" --tags decision
python scripts/brain_cli.py search "customer storage"
python scripts/brain_cli.py show <id-or-title>
# Organize and connect
python scripts/brain_cli.py list --collection Decisions --sort updated
python scripts/brain_cli.py relate <from-id> <to-id> --type references
python scripts/brain_cli.py traverse <id> --depth 2
# Recoverable lifecycle
python scripts/brain_cli.py delete <id>
python scripts/brain_cli.py restore <id>
python scripts/brain_cli.py summary
Run python scripts/brain_cli.py --help for the complete command set, including
point-in-time and affect-aware recall, distillation, archival, and brain merge.
For a content-free install and pairing report, run the read-only doctor:
python scripts/brain_doctor.py --json
It checks the package, MCP protocol, storage surface, journals, and paired
database/Bundle digests without opening a writable database or printing note
contents. Add --strict when an uninitialized brain should fail the check.
MCP
Run the dependency-free stdio server:
python /absolute/path/to/second-brain/scripts/brain_mcp.py
Register that command using your host's MCP configuration shape. The common payload is:
{
"mcpServers": {
"second-brain": {
"command": "python",
"args": ["/absolute/path/to/second-brain/scripts/brain_mcp.py"]
}
}
}
The server and CLI operate on the same local database. Diagnostics go to
stderr; JSON-RPC alone is written to stdout.
Obsidian compatibility
Export one Markdown file per Concept:
python scripts/brain_cli.py export --format markdown --output ./MyVault
Import a vault recursively (.md and .markdown):
python scripts/brain_cli.py import ./MyVault --merge
Repository tests cover YAML frontmatter, CRLF input, recursive folders,
[[alias|label]], heading/block fragments, wikilink/manual-relation coexistence,
and OKF manual-relation rebuild. Nested relative note paths (including
.markdown) are preserved through the namespaced sb_obsidian_path extension.
This is level-2-format progress, not a native Obsidian plugin or live
two-way sync. Unknown top-level YAML blocks are preserved through the
namespaced sb_obsidian_frontmatter extension, but the importer does not
interpret every YAML type and path-qualified links are not resolved by
basename. Keep that limitation in mind before pointing it at a heavily
customized vault.
Attachments are deliberately opt-in and remain outside the canonical memory model. To mirror non-Markdown files from an existing vault during export:
python scripts/brain_cli.py export --format markdown --output ./MyVault \
--attachments-from ./OriginalVault
The mirror rejects symlinks and conflicting destination files; it is not a cross-device attachment sync protocol.
Git sync
The OKF Bundle is the bidirectional synchronization spine:
python scripts/brain_cli.py sync [--remote <git-remote>]
python scripts/sync.py ~/.secondbrain/okf <git-remote> ~/.secondbrain/brain.db
Sync exports files, commits, pulls with rebase, parks conflicting Markdown as
*.conflict.md, pushes, then rebuilds SQLite. The generated Bundle .gitignore
blocks key, database, environment-secret, and local pair-state patterns from
staging. If a pull or rebuild is interrupted, the sync journal makes the Bundle
authoritative on retry; it never exports the stale pre-pull database over newer
Markdown.
Backups: local, S3/GCS/Azure/R2/B2, Postgres, Supabase
Backups are immutable, content-addressed snapshots. They are deliberately one-way mirrors, not a concurrent-edit protocol.
Local reference backend:
python scripts/brain_cli.py backup --backend local --store ./backups \
--bundle ~/.secondbrain/okf
python scripts/storage_cli.py push --backend local \
--store ./backups --bundle ~/.secondbrain/okf
python scripts/storage_cli.py pull --backend local \
--store ./backups --dest ./restored-okf
python scripts/bundle.py rebuild ./restored-okf ./restored-brain.db
Manage the optional encryption key through the main CLI:
key init refuses to overwrite an existing key file.
python scripts/brain_cli.py key status
python scripts/brain_cli.py key init
For a restored brain that should become a normal paired working store, open it through the coordinator once (this writes the local pair receipt):
python scripts/brain_cli.py --db ./restored-brain.db \
--bundle ./restored-okf stats
The low-level bundle.py rebuild command remains useful for disposable
projections, but it intentionally does not claim ownership of a user's paired
working store.
Any configured rclone remote uses the same verified snapshot format. This covers S3, GCS, Azure Blob, Cloudflare R2, Backblaze B2, MinIO, Wasabi, and many other providers without putting credentials on this CLI's command line:
python scripts/storage_cli.py push --backend rclone \
--remote s3:my-bucket/second-brain --bundle ~/.secondbrain/okf
PostgreSQL and Supabase use an optional lazy adapter:
pip install "psycopg[binary]"
export SECONDBRAIN_POSTGRES_DSN='postgresql://...'
python scripts/storage_cli.py push --backend postgres \
--bundle ~/.secondbrain/okf
Supabase is PostgreSQL here: pass its database connection string through a named
environment variable with --dsn-env SUPABASE_DB_URL. No live cloud account is
exercised in CI. Exact guarantees and restore behaviour are in
references/storage.md.
For the complete publication and qualification gates, see the public release checklist.
Security before remote sync
The local database and ordinary Markdown exports are plaintext. Optional Fernet
encryption protects Concepts tagged private or psych, plus Episode and
RelationshipModel types, when a key is configured:
pip install cryptography
python scripts/crypto.py init
export SECONDBRAIN_REQUIRE_ENCRYPTION=1
Set SECONDBRAIN_REQUIRE_ENCRYPTION=1 before any remote export or snapshot.
Without strict mode and without a configured key, the legacy export path warns
but can still write sensitive Concepts as plaintext. Remote snapshots preserve
Bundle bytes; they do not add encryption themselves. As defense in depth, the
rclone and PostgreSQL/Supabase backends inspect the verified snapshot and refuse
recognized plaintext private Concepts before any remote I/O. A deliberately
dangerous --allow-plaintext-private override exists for exceptional migrations.
Read SECURITY.md and the threat model before
using psychological or third-party personal data. Never sync secret.key.
Evidence and development
Reproduce the public release gate:
python scripts/validate_skill.py .
python scripts/run_corpus.py
python scripts/ship_gate.py
The integrated suite contains 262 tests. It covers the engine, CLI, OKF export/rebuild, sync, encryption paths, MCP subprocess, skill packaging, Obsidian-format behaviour, and storage snapshots. CI runs on Ubuntu, Windows, and macOS with Python 3.10 and 3.14. Optional-crypto and platform-specific tests skip when their prerequisite is unavailable.
Project status and remaining gates:
Open-source SaaS direction
The open core should remain completely useful offline: format, CLI, SQLite projection, MCP, Obsidian path, cryptography, git sync, backup contract, and provider adapters. A paid product can operate the difficult layer around it:
- device and workspace fleet health;
- scheduled encrypted snapshots and restore drills;
- BYOC control plane, RBAC, audit, SSO/SCIM, alerts, and support;
- team onboarding and migration.
The recommended first offer is a paid Agent Memory Portability Setup for a small AI consultancy, before building a broad hosted platform. The full buyer, pricing hypotheses, technical boundary, and 90-day gates are in docs/OPEN_SOURCE_SAAS.md.
Contributing
Start with an issue that names the user-visible behaviour and evidence required. New storage adapters should conform to the snapshot contract rather than making their service authoritative. New agent integrations should add a real host-version handshake, not only a configuration snippet.
Run the release gate before opening a pull request. Security issues should follow SECURITY.md, not a public issue.
MIT licensed. Your knowledge is your intellectual history; keep the files.
second-brain MCP questions
How is the data stored?
The canonical store is an OKF-flavoured Markdown Bundle, while SQLite is used as a disposable search index.
Does it require an account?
No, the Python core uses the standard library and no account is required to use the service.
How can I sync my memory across devices?
You can use Git for bidirectional synchronization of the Markdown bundle.