agent-natalie

agent-natalie — Personal Assistant MCP Server for Obsidian

A portable personal assistant MCP server for AI coding agents. Natalie lives in your Obsidian vault — memory, tasks, contacts, and conventions stay fully local and offline, no cloud or external API required.

Tested with Claude Code, OpenCode, Mistral Vibe, Goose, and Codex. Any MCP-compatible agent client should work — see Connecting your agent below.

What it does

• Memory — indexes your vault with FTS + semantic search (fastembed, fully offline)
• Tasks — discovers and manages checkbox tasks across your notes
• Documents — files and retrieves reference material
• Contacts — maintains entity/person reference cards
• Conventions — remembers your working rules and applies them before acting
• Personas — ships 8 preset personalities; drop a .md file to add your own

---

Requirements

• Python 3.11+
• uv (installed automatically by install.sh if missing)
• Obsidian (optional but recommended — Natalie falls back to direct file I/O without it)

---

Install

bash <(curl -fsSL https://raw.githubusercontent.com/sjmgarnier/agent-natalie/main/install.sh)

The script:

1. Installs uv if missing
2. Creates ~/.natalie/.venv/ with an isolated Python environment
3. Prompts for your vault path, persona, and agent clients
4. Scaffolds the vault and configuration for the selected clients
5. Builds the initial search index

Note: Step 5 downloads the embedding model (~130 MB) on first run. This is cached after the first sync. Allow extra time on slow connections.

---

Obsidian setup

After running install.sh, complete these steps in Obsidian before use.

1. Add the vault

Open Obsidian → Open folder as vault → select the vault path you provided to install.sh.

2. Enable the CSS snippets

The dashboard layout requires three CSS snippets that install.sh already copied into .obsidian/snippets/. Enable them:

1. Go to Settings → Appearance → CSS snippets
2. Toggle on natalie-dashboard, MCL Multi Column, and MCL Wide Views

If the snippets are not listed, click the folder icon to refresh the snippets directory. If the multi-column layout still doesn't render, open the Command palette (Cmd+P / Ctrl+P) and run Reload app without saving.

3. Install and configure Dataview

The dashboard uses Dataview for live queries. Install it from the community plugin browser:

1. Settings → Community plugins → Browse
2. Search Dataview → Install → Enable
3. Open Dataview settings → enable Enable JavaScript Queries and Enable Inline JavaScript Queries

Without Dataview the dashboard will show raw code blocks instead of rendered tables and task lists.

4. Install the Tasks plugin

The Tasks plugin enables rich task metadata — due dates, priorities, and recurrence rules — that Natalie can read and write via task_capture and task_complete.

1. Settings → Community plugins → Browse
2. Search Tasks → Install → Enable

Without the Tasks plugin, Natalie falls back to plain checkboxes and the metadata fields (due, priority, recurrence) will not be available.

5. Open the Dashboard

Click Dashboard.md in the vault root. Switch to Reading view if it doesn't render automatically.

---

Connecting your agent

natalie-server is a standard MCP server. Any MCP-compatible agent client can use it. natalie init pre-wires Claude Code, OpenCode, Mistral Vibe, Goose, and Codex when selected; for other clients follow the generic instructions below.

Selecting clients

The installer asks which clients to configure. Direct CLI use accepts a repeatable option:

natalie init /path/to/vault --client codex
natalie init /path/to/vault --client claude --client codex
natalie init /path/to/vault --client all

The exact selection is stored in Natalie/config.toml and reused on later runs. Vaults without stored selection retain the previous default—Claude Code, OpenCode, Vibe, and Goose—so Codex is never added silently. Changing the selection stops future management of an omitted client but does not delete files that Natalie previously generated for it.

Claude Code

Start Claude Code from inside the vault directory:

cd /path/to/your/vault
claude

Claude Code reads .mcp.json and connects to natalie-server automatically. The Natalie tools (memory_search, note_write, task_list, …) will appear in the tool list. natalie sync runs automatically as a post-tool-use hook after every tool call.

OpenCode

Start OpenCode from inside the vault directory:

cd /path/to/your/vault
opencode

OpenCode reads opencode.json and connects to natalie-server automatically. natalie sync runs automatically as a post-tool-use hook after every tool call.

Mistral Vibe

Start Mistral Vibe from inside the vault directory:

cd /path/to/your/vault
vibe

Mistral Vibe reads .vibe/config.toml and connects to natalie-server automatically. If you enabled experimental hooks during natalie init, natalie sync runs automatically after every agent turn (requires Mistral Vibe v2.9.0+). Otherwise, run natalie sync manually after sessions that modify vault files.

Goose

natalie init registers natalie-server in Goose's global config (~/.config/goose/config.yaml) and creates a project plugin at <vault>/.agents/plugins/natalie/ with a PostToolUse hook that runs natalie sync after every tool call.

Start Goose from inside the vault directory:

cd /path/to/your/vault
goose

Goose discovers the natalie extension globally and the project plugin automatically. Outside a vault directory, all natalie tools return a clear "no vault found" message — the extension loads cleanly without broken-extension errors.

Codex

Select Codex during installation or add it to an existing vault explicitly:

natalie init /path/to/your/vault --client claude --client codex
cd /path/to/your/vault
codex

Codex reads .codex/config.toml, starts natalie-server with the vault as its working directory, discovers Natalie skills from .agents/skills/, and loads the project natalie-assistant from .codex/agents/. Trust the vault project so Codex loads its project configuration, then use /hooks to review and trust the once-per-turn Natalie sync hook. Use /mcp to verify the server. Restart Codex if it was already running when configuration changed.

This local stdio setup works with local Codex clients—the Codex CLI, IDE extension, and local tasks in the ChatGPT desktop app. Hosted ChatGPT web cannot launch the local server.

Other MCP clients

Point your client at the natalie-server binary and run it from inside the vault directory:

command: /Users/<you>/.natalie/.venv/bin/natalie-server
args:    []
cwd:     /path/to/your/vault

The server uses stdio transport. It discovers the vault by walking up from its working directory looking for .natalie/natalie.db, so the working directory must be set to the vault root (or any subdirectory of it).

Run natalie sync from the vault directory any time you add new notes outside of an agent session.

---

CLI commands

natalie sync [--full] [--quiet]    # Rebuild vault index; --quiet is for lifecycle hooks
natalie config --persona donna     # Switch persona and regenerate CLAUDE.md / AGENTS.md
natalie config --regen             # Regenerate CLAUDE.md / AGENTS.md without changing persona
natalie init <vault-path> [--client NAME]...  # Scaffold and select agent clients

---

MCP tools

---

Companion skills & agents

natalie init installs two companion components alongside the MCP server:

natalie-delegate (skill)

A skill loaded into Natalie's context on every session. It teaches Natalie when and how to delegate tasks to natalie-assistant — covering suitability criteria (complexity, duration, parallelisability vs. criticality, uncertainty, cost-to-specify), brief format, completion verification, and failure fallback. Installed to <vault>/.agents/skills/natalie-delegate/SKILL.md and symlinked into .claude/skills/ for Claude Code.

natalie-assistant (subagent)

A pre-configured background subagent with full access to natalie MCP tools. Natalie can delegate long-running or parallelisable tasks to it — research, filing, enrichment — and the assistant stores all results in the vault before returning. Installed per client:

---

Personas

Custom personas

Drop a .md file in <vault>/Natalie/personas/:

---
name: My Assistant
source: Original
tone:
  - helpful
  - direct
---

Your persona prose here.

Then activate it:

natalie config --persona my-assistant

---

Configuration

Edit <vault>/Natalie/config.toml, then run natalie config --regen:

[persona]
name = "natalie"

[memory]
embedding_model = "BAAI/bge-small-en-v1.5"

[skills]
preferred = []   # e.g. ["superpowers", "r-lib"] — agent will prefer these
denied    = []

[mcps]
preferred = []   # e.g. ["obsidian", "github"]
denied    = []

[clients]
enabled = ["claude", "codex"]

[features.documents]
directory = "Natalie/Documents"

[features.contacts]
directory = "Natalie/Contacts"

---

Known limitations

Changing the embedding model — Existing embeddings are incompatible with a new model. After changing embedding_model in config.toml, run natalie sync --full to rebuild the index from scratch.

Single active session per vault — natalie.db lives inside the vault. If you sync your vault across machines (iCloud, Dropbox, Syncthing, or similar), running natalie-server on two machines simultaneously against the same vault risks SQLite WAL corruption. Keep one active session at a time.

---

Upgrade

bash <(curl -fsSL https://raw.githubusercontent.com/sjmgarnier/agent-natalie/main/install.sh)

The script detects an existing install and offers to upgrade in place. Leave the client prompt blank to retain the vault's stored selection. Older vaults without a [clients] section retain the legacy four-client set until Codex is explicitly selected.

---

Uninstall

bash <(curl -fsSL https://raw.githubusercontent.com/sjmgarnier/agent-natalie/main/uninstall.sh)