Obsidian Second Brain

Local MCP server and Codex skill for Obsidian-backed project memory.

This project turns an Obsidian vault into durable project context for AI coding agents. It is meant to complement tools like CodeGraph:

• CodeGraph answers: "How does this code work?"
• Obsidian Second Brain MCP answers: "What do we know about this project, bug, feature, decision, session, release, and next action?"

The server is local-first. It reads and appends Markdown files in your Obsidian vault. It does not require a cloud service, API key, or hosted database.

What It Provides

MCP tools:

• project_memory_start - load a compact project context pack before meaningful work.
• project_memory_status - check repo-to-Obsidian linkage.
• project_memory_log_bug - record bug reports, investigation, fixes, verification, and next actions.
• project_memory_log_feature - record feature intent, implementation, verification, and follow-up.
• project_memory_record_decision - record durable choices and rationale.
• project_memory_close_session - write a session closeout with outcome, changed files, verification, open questions, next actions, and deployment status.

CLI commands:

• obsidian-second-brain-mcp serve
• obsidian-second-brain-mcp init
• obsidian-second-brain-mcp status
• obsidian-second-brain-mcp agents-snippet

Codex skill:

• skills/obsidian-second-brain-mcp/SKILL.md

Requirements

• Node.js 20 or newer.
• An Obsidian vault stored on the local filesystem.
• An AI agent that supports MCP over stdio, such as Codex CLI.

Install From Source

git clone https://github.com/YOUR-USERNAME/obsidian-second-brain-mcp-and-skill.git
cd obsidian-second-brain-mcp-and-skill
npm install
npm run build
npm link

Confirm the CLI is available:

obsidian-second-brain-mcp --help

Configure Codex MCP

Add this MCP server to your Codex config. The exact config file location may vary by Codex version, but a common location is:

~/.codex/config.toml

Example:

[mcp_servers.obsidian_second_brain]
command = "obsidian-second-brain-mcp"
args = ["serve"]

Restart Codex after editing MCP config.

Link A Repo To An Obsidian Project

From the repo you want to document:

obsidian-second-brain-mcp init \
  --project "Example Project" \
  --vault "/absolute/path/to/your/Obsidian Vault" \
  --obsidian-project "01_Projects/Example Project" \
  --write-agents

This creates:

.obsidian-second-brain.json
AGENTS.md

It also creates missing starter notes inside the configured Obsidian project folder:

Project Brief.md
Bugs.md
Decisions.md
Runbook.md
Next Actions.md
Activity Log.md
Changelog.md
Releases.md
Open Questions.md
Session Log.md

Check the link:

obsidian-second-brain-mcp status

Repo Config

Each linked repo has a .obsidian-second-brain.json file:

{
  "projectName": "Example Project",
  "projectCode": "EP",
  "vaultPath": "/absolute/path/to/your/Obsidian Vault",
  "obsidianProjectPath": "01_Projects/Example Project",
  "hubNote": "EP_ExampleProject_Home.md"
}

If you do not want to store vaultPath in each repo, omit it and set:

export OBSIDIAN_VAULT_PATH="/absolute/path/to/your/Obsidian Vault"

Do not commit .obsidian-second-brain.json if it contains private local paths. Use examples/project-config.example.json as the public template.

Install The Codex Skill

Copy the skill folder into your Codex skills directory:

mkdir -p ~/.codex/skills
cp -R skills/obsidian-second-brain-mcp ~/.codex/skills/

Restart Codex. The skill tells Codex when to use the MCP tools during project work.

Intended Agent Workflow

When you start work in a linked repo, the agent should:

1. Call project_memory_start with the repo path.
2. Use the returned project notes as durable context.
3. For bugs, call project_memory_log_bug during investigation and again when fixed or verified.
4. For features, call project_memory_log_feature when scope or implementation becomes clear.
5. Use project_memory_record_decision for durable choices.
6. Before final response, call project_memory_close_session if meaningful work happened.
7. Ask whether to deploy or release when deployment status is relevant but not known.

Privacy

This repo contains no personal vault paths, project names, API keys, or private notes.

The MCP server runs locally and only reads/writes files in the vault path you configure. It does not send your notes anywhere.

You should still avoid committing:

• .obsidian-second-brain.json files with private paths.
• Obsidian notes copied from a private vault.
• Secrets or API keys in project notes.

Development

npm install
npm run typecheck
npm run build

Run the server manually:

obsidian-second-brain-mcp serve

License

MIT