second_brain
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@second_brain search my vault for notes on the Q3 launch and summarize them"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
第二大脑 · Second Brain
让 AI 在后续任务中找回有来源的知识、过去的决策和真实执行经历。
Second Brain 是一个本地优先的知识与记忆工具箱:用 Markdown 和 Obsidian 组织资料,用 MCP 为 AI 客户端提供检索、阅读、明确收件和知识卡回写,用追加式账本保存任务经过,再用治理脚本生成复盘候选和健康报告。它适合长期项目协作、个人知识管理和需要追溯依据的 AI 工作流。
代码、模板和示例采用 MIT 许可证。仓库提供通用实现与重新编写的示例库;使用者的资料库、会话日志、账本、数据库和账户配置由使用者在本机单独管理。
主要功能
功能 | 实际行为 |
知识检索与阅读 | 按标题、路径、正文关键词和知识状态排序,返回有界摘要与 Vault 相对路径,再读取完整卡片;支持中文。 |
核心记忆注入 | 从索引和核心卡片生成紧凑上下文;可通过 MCP 或支持命令 Hook 的宿主加载。 |
明确收件与知识回写 | 将用户选定文本存入 Inbox、脱敏并按内容去重;创建或更新带来源、置信度和证据时间线的知识卡。 |
任务经历记忆 | 保存任务开始、事件、结果和反思;用文件锁、序号、幂等标识和 SHA-256 哈希链校验记录完整性。 |
知识治理 | 扫描增量资料、隔离可疑敏感内容、生成蒸馏候选和健康指标;经验达到独立回归门槛后进入评审队列。 |
跨工具接入 | 提供 MCP、Codex 会话日志与 Hook、PowerShell 收件管线,以及可选 WorkBuddy 原生运行证据适配器。 |
“自生长”在这里有明确流程:收集证据 → 生成候选 → 真实复核 → 回写知识 → 保存版本。候选评分和格式有效的回执不能代替事实验证、用户授权或任务业务成功。模型调用、宿主 Hook 注册和定时调度由接入方提供。
Related MCP server: mcp-vault-reader
快速运行
需要 Node.js 22+。完整治理和测试还需要 Python 3.11+、PowerShell 7+(pwsh);Python 代码仅依赖标准库。Obsidian 是可选的资料浏览工具,终端演示可以独立运行。
git clone https://github.com/a865948732-jpg/second-brain.git
cd second-brain
npm ci --ignore-scripts --no-audit --no-fund
npm run init:vault
npm run demo
npm run smokeinit:vault在.local/vault创建通用资料库,包括数据目录、示例卡片与健康策略;目标目录已有内容时拒绝覆盖。demo每次在新的.local/demo-*/vault中完成“收件去重 → 写卡 → 检索与回读 → 记录任务 → 召回与验链”,并输出实际断言结果。smoke启动真实 stdio MCP 子进程,检查 11 个工具、2 个资源、核心上下文、检索和状态。它读取当前配置的 Vault。.local/被 Git 忽略。代码使用仓库位置解析默认路径,可以从其他工作目录启动。
打开 Obsidian,选择“打开文件夹作为库”,指向 .local/vault,即可浏览示例。初始化生成空 .obsidian 目录作为治理检查的库标记,不包含个人界面或插件配置。
指定一个新库:
npm run init:vault -- --path "/absolute/path/to/new-vault"使用已有库时,先确认它的目录结构、权限与版本备份,再按 配置说明 设置 SECOND_BRAIN_VAULT。初始化命令不用于向已有库覆盖模板。
接入 AI 客户端
在支持 stdio MCP 的客户端中注册以下入口,并替换两个绝对路径:
{
"mcpServers": {
"second_brain": {
"command": "node",
"args": ["/absolute/path/to/second-brain/packages/mcp/index.js"],
"env": { "SECOND_BRAIN_VAULT": "/absolute/path/to/your/vault" }
}
}
}Windows 路径可写为 C:/Projects/second-brain/...。Codex TOML 示例、Hook 入口和权限设置见 接入配置 与 工作流。npm start 启动的是 stdio 协议进程,等待客户端消息时终端不会显示聊天界面。
典型调用顺序:
second_brain_search(query="当前问题")
→ second_brain_read(path="搜索返回的相对路径")
→ 结合当前证据回答或执行
→ 在明确授权范围内 capture / upsert_card / task_finish只读工具和写入工具分别标注在 MCP 接口表。接入方应使用宿主提供的工具授权机制;协议中的提示字段不能代替权限控制。
项目结构
second-brain/
├── packages/
│ ├── config.cjs # 默认路径、环境变量和 Vault 路径约束
│ ├── mcp/ # MCP 服务、知识读写、上下文与生命周期 Hook
│ └── runtime/ # 经历账本、文件锁、召回和候选评分
├── hooks/ # Codex 日志、增量同步与定向补回
├── governance/ # 蒸馏候选、敏感资格门和分层健康检查
├── integrations/workbuddy/ # 可选的原生运行身份、终态回执和 ingress 验证
├── scripts/
│ ├── inbox/ # PowerShell 显式收件与队列路由
│ └── *.mjs # 初始化、演示、验证、发布检查与账本对账
├── templates/vault/ # 通用 Vault 骨架和健康策略
├── examples/ # MCP 配置及可运行接口调用示例
├── tests/ # 可移植性、路径隔离和收件管线的集成回归
├── docs/ # 架构、配置、流程、验证和来源说明
└── .github/ # Windows / Ubuntu CI 与问题模板资料库内部使用以下分层:
目录 | 职责 |
| 明确选定、尚待分类的收件。 |
| 原始证据;应用工具只读。 |
| 带来源的知识、决策、习惯和项目卡片。 |
| 专题与长期问题。 |
| 文章、报告及其他成果。 |
| 每日/每周复盘、候选队列、运行记录和待归档。 |
| 可复用模板、流程与显式健康策略。 |
| 图片、PDF、音视频等附件,由使用者管理。 |
每个生产模块的输入、输出、依赖和核心逻辑见 架构说明。可按“先了解目录 → 阅读接口 → 跟随一条实际流程”的顺序进入代码。
验证与开发
npm test
npm run check:releasenpm test 顺序运行 Node 回归、Python 治理回归和 WorkBuddy 夹具回归。测试使用独立临时资料库与数据库;PowerShell 收件测试通过显式 -Text 输入。check:release 检查提交候选中的私人文件形态、凭据形态、个人硬编码路径、许可证、配置与文档链接。
验证说明 区分本地测试、真实 MCP 子进程和宿主运行的覆盖范围;贡献指南 说明开发入口与提交要求。代码以 JavaScript、Python 和 PowerShell 源文件直接运行,无需额外的项目编译步骤。
实际使用边界
检索采用有界关键词评分;大型资料库需要进一步评估覆盖率与召回效果。账本每次读取和追加都会验证完整哈希链,当前上限为 100000 条;哈希链提供完整性检查,其信任仍取决于本机存储与历史版本。脱敏规则识别常见形态,使用者仍应在输入前移除私人信息。
Hook 的日志记录、治理候选、WorkBuddy 原生证据和最终业务结果分别验收。WorkBuddy 接入依赖特定数据库与终态消息结构,参见 适配器说明。仓库中的自动化相关代码不会自行创建计划任务。
资料写入后,根据实际修改路径更新索引并在资料库自己的 Git 仓库中定向提交。归档保留历史文件,原始证据保持只读。详见 数据与安全说明 和 来源与整理范围。
Available Tools
11 toolssecond_brain_captureCapture an explicit second-brain inbox itemAIdempotent
Save text explicitly marked by the user for retention into 00_Inbox/WorkBuddy. The tool redacts common credentials, is idempotent by content, and cannot write the evidence or knowledge layers.
Inputs: text (required), title, source, sourceUrl. Returns: path, created, redacted, captureId, +1 more
second_brain_core_contextLoad core second-brain contextARead-only
Return the compact core-principles context used by the SessionStart hook.
Inputs: no named parameters. Returns: context
second_brain_readRead second-brain noteARead-only
Read a Markdown note returned by second_brain_search. Hidden tool/config paths are blocked; 01_Sources is readable but never writable.
Inputs: path (required), maxChars. Returns: path, content, truncated
second_brain_recall_experienceRecall verified second-brain experiencesARead-only
Retrieve prior task outcomes and lesson candidates by query, task type, project, outcome, or error signature. Results are candidates with evidence levels and a receipt.
Inputs: limit, query, outcome, project, +2 more. Returns: receipt, results
second_brain_record_eventRecord second-brain task eventA
Append one redacted action, result, failure, verification, or checkpoint event to the current task ledger.
Inputs: taskId (required), eventType (required), event. Returns: record, taskId, created
second_brain_score_candidatesScore second-brain action candidatesBRead-only
Rank candidates only when safe:boolean and bounded numeric evidence fields are explicit; invalid or unsafe candidates are held.
Inputs: candidates (required). Returns: results
second_brain_searchSearch second brainARead-only
Search long-term memory before answering or acting on user preferences, project history, prior decisions, tools, or recurring workflows. Results are candidates; read the note before consequential use.
Inputs: query (required), limit, scopes. Returns: query, results
second_brain_statusInspect second-brain statusARead-only
Report readable Markdown counts and the latest modification time without changing the vault.
Inputs: no named parameters. Returns: vault, counts, latestModified
second_brain_task_finishFinish second-brain task with reflectionCIdempotent
Append outcome, verification, reflection, and an optional lesson candidate. Unverified results remain candidates and cannot be promoted automatically.
Inputs: taskId (required), outcome (required), reflection (required), result, +5 more. Returns: record, taskId, created
second_brain_task_startStart second-brain task envelopeBIdempotent
Append an auditable task-start envelope with authority and retrieval receipt. It never writes 01_Sources or promotes knowledge.
Inputs: goal (required), taskId (required), source, project, +3 more. Returns: record, taskId, created
second_brain_upsert_cardUpsert second-brain knowledge cardBIdempotent
Create or update one structured card in 02_Knowledge. It cannot delete, move, or write 01_Sources. After success, update the vault index/log as needed and make a focused git commit.
Inputs: tags (required), type (required), title (required), source (required), +5 more. Returns: path, created, updated, gitCommitRequired
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
The tools separate reasonably well by layer: read/search for retrieval, capture for inbox writes, upsert_card for knowledge writes, and task_start/record_event/task_finish for ledger lifecycle. There is some conceptual adjacency between search and recall_experience, and between record_event and task_start/task_finish, but the descriptions clarify their distinct scopes.
All names use the predictable second_brain_ prefix and snake_case, which makes the set easy to scan. Most names are verb-led, but a few are noun-led (core_context, status, task_start), so the pattern is slightly mixed rather than uniform.
Eleven tools is well-scoped for a personal memory system with retrieval, capture, structured knowledge, task lifecycle, events, recall, and candidate ranking. Each tool appears to earn its place without excessive fragmentation.
The surface covers the core lifecycle: search/read, capture, upsert knowledge cards, task start/event/finish, experience recall, and candidate scoring. Minor gaps remain around explicit deletion/archiving/forgetting and index/log maintenance, though some restrictions appear intentional for safety.
Maintenance
Related MCP Connectors
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Personal context for every AI: search, read, and write back to your private Markdown library.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to read, write, search, and navigate Obsidian vault notes with support for CRUD operations, full-text search, graph navigation, daily notes, and frontmatter management.3,713 npm-
- AlicenseAqualityDmaintenanceEnables AI assistants to search, read, and traverse Markdown note vaults (Obsidian-compatible) with full-text search, backlinks, knowledge graphs, and a persistent memory system for cross-session context.164 npm4MIT
- AlicenseAqualityCmaintenanceEnables AI agents to use Obsidian vaults as persistent, bidirectional knowledge workspaces with wikilink/backlink resolution, structured frontmatter/tag indexing, task aggregation, and Obsidian Headless Sync.11MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to search and retrieve notes from a local Markdown vault using hybrid keyword/semantic search, and to save typed memories with append and guarded replacement operations.MIT