Content
# Second Brain
A **personal memory system that mimics the human brain and can be accessed by AI agents**.
<img width="2238" height="1496" alt="image" src="https://github.com/user-attachments/assets/b3a0a9b9-bfab-4577-8aa8-6c00686c70c7" />
It's not just a note-taking software, but a memory system that can **consolidate, forget, associate, and be triggered by a sentence**. Memories are stored in a local Obsidian knowledge base (Markdown, which you have full control over). Through an MCP server, any AI agent (such as Claude Code / Claude Desktop) can directly read and write to it - and follow the built-in operation protocol.
## ✨ Features
- **Brain-like hierarchy**: Inbox (working memory) → Core memory / Semantic / Episodic / Procedural memory / Entity graph
- **Memory lifecycle**: Salience, strength, forgetting curve, spaced repetition - important memories stay, trivial ones fade away
- **Cue-triggered**: Each memory has `cues` (sensory/original phrase/context/emotion), which can be triggered by a sentence or a smell
- **Knowledge graph**: People/places/things/concepts as entities, connected by relationships, forming an associative network with bidirectional links
- **Core memory**: Lifelong memories (`tier: core`) that never decay or archive
- **Self-correction**: Small corrections automatically leave a trail; overriding facts/deleting requires user confirmation; fading instead of erasing
- **Agent access**: MCP exposes 11 tools, and agents know "who you are" upon launch
- **Protocol as product**: `AGENTS.md` constrains all agents - honest, no silent modifications, overriding requires confirmation, and full trail logging
## 🚀 Quick Start (3 steps)
```bash
# 1. Clone (or click GitHub's "Use this template")
git clone https://github.com/<your-username>/second-brain.git
cd second-brain
# 2. One-click installation (install MCP dependencies + register with Claude Code)
./setup.sh
# 3. Open the vault/ folder with Obsidian → start a new Claude Code session → done ✅
```
Then, try it in Claude Code:
- 「**See my second brain**」→ agent calls `brain_overview`, reads the protocol, and learns about you
- 「**Remember: I started building my second brain today**」→ agent calls `remember` to write to the vault
- 「**Did I remember anything about X before?**」→ agent calls `recall` to search
> Requires: Node.js ≥ 18, [Obsidian](https://obsidian.md), [Claude Code](https://claude.com/claude-code) (or any MCP client).
## 📁 Structure
```
second-brain/
├── README.md this file
├── setup.sh one-click installation script
├── vault/ ← open this with Obsidian (your brain)
│ ├── AGENTS.md Agent operation protocol (constitution)
│ ├── 00-Home.md homepage
│ ├── 00-Inbox · Inbox/ working memory, to be consolidated
│ ├── 05-Core · Core Memory/ never forget
│ ├── 10-Semantic · Semantic Memory/ facts/concepts/self-portrait
│ ├── 20-Episodic · Episodic Memory/ when and where (by date)
│ ├── 30-Procedural · Procedural Memory/ how-to (SOP)
│ ├── 40-Entities · Entity Graph/ people/places/things/concepts
│ ├── 90-Consolidation · Consolidation Log/ consolidation records + correction log
│ └── _templates/ three memory templates
├── mcp/ MCP server (Node)
│ ├── package.json
│ └── server.js
└── tools/ toolset (gradually完善)
└── web-clipper/ web clipping: browser extension + local clipping service
```
## 🔧 MCP Tools (11)
| Tool | Function | Autonomous level |
|------|----------|-------------------|
| `brain_overview` | Overview (待核查/who I am/core/entities/concepts) | — |
| `get_protocol` | Read operation protocol | — |
| `recall` | Mixed search (keywords + weighted + importance) | — |
| `get_memory` | Read full text | — |
| `remember` | Write new memory | 🟢 |
| `revise_memory` | Small correction (version +1, leave a trail) | 🟡 |
| `supersede_memory` | Override incorrect memory (old retained) | 🔴 requires confirmation |
| `flag_memory` | Mark for review | 🟢 |
| `detect_contradictions` | Scan for suspected duplicates/same topic | 🟢 |
| `list_memories` | List memories | — |
| `forget` | Forget (soft archive/hard delete) | 🔴 hard delete requires confirmation |
## 🧰 Toolset (`tools/`)
Tools around the second brain, gradually完善.
### 📎 web-clipper (web clipping)
While browsing, one-click to save "title/URL/selected text/remark" to the brain's inbox:
1. Start local clipping service: `cd tools/web-clipper && node server.js`
2. Install extension: `chrome://extensions` → enable "Developer mode" → "Load unpacked" → select `tools/web-clipper/extension/`
3. Click the 🧠 icon on any webpage → add remark/tags → "Save to second brain"
4. Content lands in `vault/00-Inbox · Inbox/web/`, to be consolidated into formal memories
See [`tools/web-clipper/README.md`](tools/web-clipper/README.md) for details.
## ⚙️ Customization
- **Change vault location**: default `vault/` (relative to server). If moved, pass `-e VAULT_PATH=/your/path` during registration.
- **Connect other MCP clients** (e.g., Claude Desktop): add a stdio server in the client's config:
```json
{
"mcpServers": {
"second-brain": {
"command": "node",
"args": ["/absolute/path/mcp/server.js"],
"env": { "VAULT_PATH": "/absolute/path/vault" }
}
}
}
```
- **Enable templates**: in Obsidian settings, enable the core plugin "Templates", and set the template folder to `_templates`.
## 🧩 Design Principles
Core concept: **Memory is not a filing cabinet, but an operating brain**. Resemblance comes from hierarchy, and likeness comes from mechanisms (consolidation, forgetting, association, and reconsolidation). Trust comes from protocol (honest, no silent modifications, overriding requires confirmation, and full trail logging). Storage-wise, **Markdown is the single source of truth**, and all indexes can be rebuilt - data is transparent, git-able, editable by hand, and not locked by vendors.
## 📄 License
MIT
