# Obsidian Second Brain MCP and Skill

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

```bash
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:

```bash
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:

```text
~/.codex/config.toml
```

Example:

```toml
[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:

```bash
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:

```text
.obsidian-second-brain.json
AGENTS.md
```

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

```text
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:

```bash
obsidian-second-brain-mcp status
```

## Repo Config

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

```json
{
  "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:

```bash
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:

```bash
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

```bash
npm install
npm run typecheck
npm run build
```

Run the server manually:

```bash
obsidian-second-brain-mcp serve
```

## License

MIT