Second Brain

One persistent, shared memory for you, your team, and every AI assistant you work with.

Second Brain is a knowledge and memory platform. People and AI assistants (Claude, Cursor, Copilot, ChatGPT, custom agents) read from and write to the same store of Markdown notes: projects, decisions, topics and session logs. You open a new chat on any machine, with any assistant, and it already knows what you were doing, what you decided and why, and what comes next.

It begins as a personal daily-driver and is designed from the start to be sold to businesses as an internal knowledge tool, with multi-tenant isolation, sharing, SSO and audit trails.

Status: Phase 0, planning. This repository holds the product plan, architecture and engineering standards. Code starts in Phase 1 (see Roadmap).

The problem

Related MCP server: agent-memory-server

What we are building

1. Memory server (MCP + REST): a TypeScript service on Cloudflare Workers that exposes memory tools to any MCP client.

2. Vault: Markdown notes with YAML frontmatter and [[wikilinks]], stored in Git (the source of truth). Each note is a project, decision, topic, session or a free note.

3. Search index: SQLite (Cloudflare D1) full-text search, plus an optional semantic layer (embeddings and vector search, merged with reciprocal rank fusion). The index is a cache that can be rebuilt from Git at any time.

4. Session ritual: context, then work, then save, then a periodic check. This is where most of the value comes from.

5. Web app: browse, search, edit, graph view, manage keys, spaces, sharing and audit logs.

6. CLI (brain): sign a machine in once, store keys in the OS keychain, auto-configure installed assistants, and run activity-logging hooks.

7. Teams and business tier: orgs, spaces, roles, invitations with consent, SSO, audit log and data export.

Core features (v1 must-haves)

• MCP tools: brain_context, brain_save, brain_search, brain_read, brain_write, brain_check, brain_projects

• Atomic multi-file saves (one commit per save)

• Heading-aware chunking and full-text search with permission filters applied inside the query

• Token-budgeted context responses, with superseded decisions hidden

• Per-machine, per-assistant API keys with scopes (read-only, project-limited), plus OAuth 2.1 for MCP clients

• Secret redaction on the client and again on the server; all memory treated as untrusted data

• Web UI for reading, editing, searching and key management

• Personal spaces, plus sharing of projects or spaces as viewer or editor

The full prioritised list is in Requirements.

Connect a client

Every MCP client connects to one URL: https://<host>/mcp. Clients that support MCP authorization (OAuth 2.1) need nothing else. The first time they connect, a browser window asks you to sign in and approve the app, and you choose whether it may write as well as read. You can disconnect it at any time in the web app.

Clients without OAuth support, scripts and hooks use a scoped API key instead (brain login, or Keys in the web app):

claude mcp add --transport http second-brain https://<host>/mcp --header "Authorization: Bearer sb_live_..."

How the OAuth flow works is described in LLD §8.

Architecture at a glance

 AI clients (Claude, Cursor, ...)   Web app   brain CLI   Git push (webhook)
            │ MCP / HTTPS              │ HTTPS     │           │
            ▼                          ▼           ▼           ▼
 ┌──────────────────── Cloudflare Worker: API gateway ────────────────────┐
 │ authN (keys / OAuth / session) → authZ (RBAC) → rate limit → router    │
 │   MCP tools   REST API   Webhooks   Admin                              │
 │        └──── domain services (Notes, Search, Session, Sharing) ────┘   │
 └───────┬───────────┬───────────┬───────────┬───────────┬────────────────┘
         ▼           ▼           ▼           ▼           ▼
    Git provider    D1 (SQLite   R2 (archives,  KV (hot     Queues + Cron
    (source of      + FTS5       backups,       lookups,    (index sync, embed,
     truth)         index, meta) exports)       rate limit) archive, rebuild)
                                                            │
                                               Vectorize + Workers AI (embeddings)

Read more: High-level design · Low-level design

Documentation map

Planned tech stack

Repository layout (target)

second-brain/
├── apps/
│   ├── server/          # Cloudflare Worker: MCP + REST + webhooks + cron consumers
│   └── web/             # React dashboard
├── packages/
│   ├── core/            # Pure domain logic: parser, chunker, ranking, budgeter, redactor
│   ├── schema/          # Zod schemas and shared types (MCP tool I/O, REST DTOs)
│   ├── db/              # D1 migrations + typed repository layer (tenant-scoped)
│   ├── vault/           # VaultStore interface + GitHub implementation
│   ├── cli/             # `brain` CLI: login, keychain, client config, hooks
│   └── config/          # Shared tsconfig / eslint / prettier
├── docs/                # This plan: product, HLD/LLD, security, ADRs
├── .github/             # CI workflows, templates, CODEOWNERS
└── README.md

Contributing

See CONTRIBUTING.md. Security issues: see SECURITY.md.

License

Second Brain is open source under the GNU AGPL-3.0. You can use, modify and self-host it freely. If you run a modified version as a network service, you must share your changes under the same licence.