convez.ai
MCP ServerProdutividadeIntermediário
sjmgarnier

Agent Natalie

sjmgarnier/agent-natalie

Assistente pessoal MCP local com Obsidian como backend de memória

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que transforma seu Obsidian em um assistente pessoal para agentes de IA (Claude Code, OpenCode). Mantém memória, tarefas, contatos e convenções localmente, sem cloud ou APIs externas, com busca semântica offline e suporte a múltiplas personalidades.

Instalação

$npx convez-ai sjmgarnier/agent-natalie

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v0.1.37
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar Claude Code ou OpenCode com seu banco pessoal de conhecimento
  • Gerenciar tarefas e projetos via MCP com sincronização de checkboxes
  • Manter contexto de trabalho (convenções, contatos, referências) offline

Veredito

Projeto robusto e bem-documentado que resolve um problema real: dar aos agentes de IA acesso seguro a contexto pessoal sem deixar o computador local. Implementação Python limpa, instalação automatizada e suporte a múltiplos clientes MCP. Recomendado para quem quer um assistente AI-native ancorado em Obsidian.

README

A tradução para o português deste README ainda está na fila.

agent-natalie — Personal Assistant MCP Server for Obsidian

PyPI Python License: MIT

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, and Goose. 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 and persona
  4. Scaffolds the vault (dashboard, CLAUDE.md, AGENTS.md, CSS snippets, MCP config)
  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, and Goose automatically; for other clients follow the generic instructions below.

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.

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]              # Rebuild vault index (--full wipes and reindexes everything)
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>          # Scaffold a new vault (called by install.sh)

MCP tools

ToolDescription
pingCheck that the server is running
watcher_statusInspect vault watcher daemon health (alive, path, thread ident)
note_listList indexed vault notes; optional directory filter
vault_statsIndex health dashboard: note count, open tasks, embedding coverage, last sync
memory_searchHybrid FTS + semantic search across vault notes
memory_storeStore an outside-vault knowledge entry
note_readRead a vault note by path
note_writeWrite or update a vault note
task_listList open (or all) tasks across the vault
task_captureAdd a task to a note
task_completeMark a task done
task_updateEdit an existing task in place (text, due date, priority, recurrence)
document_fileRegister a vault file in the document index with a semantic description
document_listList or semantically search filed documents
contact_getGet a contact card by slug
contact_updateCreate or update a contact card
contact_listList all contact slugs
contact_searchHybrid search over contacts by name, company, or notes
convention_listList conventions, optionally filtered by domain
convention_addAdd a convention
convention_updateEdit a convention in place
convention_deleteDelete a convention by ID
onboarding_statusCheck whether onboarding has been completed
onboarding_completeMark onboarding complete

Personas

PresetCharacterSource
natalieNatalie TeegerMonk
donnaDonna PaulsenSuits
moneypennyMiss MoneypennyJames Bond
smithersWaylon SmithersThe Simpsons
aprilApril LudgateParks & Recreation
finchDennis FinchJust Shoot Me!
garyGary WalshVeep
pamPam BeeslyThe Office

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    = []

[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.


Uninstall

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

Bom para

Relacionados