second-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.
• 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?"

Data is created under ~/.secondbrain/. Use --db PATH to isolate a different
brain.

What works where

“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/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/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

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:

• Compatibility and evidence
• Independent project review
• Security policy
• Threat model
• Storage contract

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.