agent-natalie 0.1.0__tar.gz

agent_natalie-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+.claude/
+*.db
+
+# macOS
+.DS_Store
+
+# local knowledge graph (machine-specific)
+.mnem/
+
+# uv lockfile — not committed for library packages
+uv.lock
+
+# internal planning / spec artifacts — keep local only
+docs/

agent_natalie-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Garnier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_natalie-0.1.0/Makefile

@@ -0,0 +1,35 @@
+.PHONY: lint format typecheck security test check install-hooks publish
+
+lint:
+	uv run ruff check natalie/ tests/
+
+format:
+	uv run ruff format --check natalie/ tests/
+
+typecheck:
+	uv run mypy natalie/
+
+security:
+	uv run bandit -r natalie/ -ll
+
+test:
+	uv run python -m pytest tests/ -v
+
+check: lint format typecheck security test
+
+install-hooks:
+	cp scripts/pre-commit .git/hooks/pre-commit
+	chmod +x .git/hooks/pre-commit
+	@echo "Pre-commit hook installed."
+
+# PyPI publish checklist:
+#   1. Bump version in pyproject.toml
+#   2. Commit and tag: git tag vX.Y.Z && git push --tags
+#   3. Set TWINE_USERNAME / TWINE_PASSWORD (or use a ~/.pypirc token)
+#   4. Run: make publish
+publish: check
+	@git diff --exit-code || (echo "ERROR: working tree is dirty — commit or stash changes before publishing"; exit 1)
+	@git diff --cached --exit-code || (echo "ERROR: staged changes present — commit before publishing"; exit 1)
+	rm -rf dist/
+	uv run python -m build
+	uv run twine upload dist/*

agent_natalie-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: agent-natalie
+Version: 0.1.0
+Summary: MCP server that turns an Obsidian vault into a personal-assistant backend for Claude Code and OpenCode
+Author-email: Simon Garnier <simon.garnier@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Simon Garnier
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: fastembed>=0.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: python-frontmatter>=1.1
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

agent_natalie-0.1.0/README.md

@@ -0,0 +1,225 @@
+# agent-natalie
+
+A portable personal assistant plugin for Claude Code and OpenCode.
+Natalie lives in your Obsidian vault and is only active when your agent
+is working from that directory.
+
+## 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`](https://docs.astral.sh/uv/) (installed automatically by `install.sh` if missing)
+- Obsidian (optional but recommended — Natalie falls back to direct file I/O without it)
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/sjmgarnier/agent-natalie agent-natalie
+bash agent-natalie/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**
+3. Press **Cmd+R** (Mac) / **Ctrl+R** (Windows) to reload Obsidian
+
+If the snippets are not listed, click the folder icon to refresh the snippets directory.
+
+### 3. Install and configure Dataview
+
+The dashboard uses [Dataview](https://github.com/blacksmithgu/obsidian-dataview) for
+live queries. Install it from the community plugin browser:
+
+1. **Settings → Community plugins → turn off Restricted Mode → Browse**
+2. Search **Dataview** → **Install** → **Enable**
+3. Open **Dataview settings** → enable **Enable JavaScript Queries**
+
+Without Dataview the dashboard will show raw code blocks instead of rendered tables and task lists.
+
+### 4. Open the Dashboard
+
+Click **Dashboard.md** in the vault root. Switch to Reading view if it doesn't render automatically.
+
+---
+
+## First run
+
+Start Claude Code from inside the vault directory:
+
+```bash
+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.
+
+Run `natalie sync` any time you add new notes outside of Claude Code.
+(It runs automatically as a post-tool-use hook inside Claude Code sessions.)
+
+---
+
+## CLI commands
+
+```bash
+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
+
+| Tool | Description |
+|------|-------------|
+| `ping` | Check that the server is running |
+| `memory_search` | Hybrid FTS + semantic search across vault notes |
+| `memory_store` | Store an outside-vault knowledge entry |
+| `note_read` | Read a vault note by path |
+| `note_write` | Write or update a vault note |
+| `task_list` | List open (or all) tasks across the vault |
+| `task_capture` | Add a task to a note |
+| `task_complete` | Mark a task done |
+| `document_file` | File a document to the documents cabinet |
+| `document_retrieve` | Retrieve a document by filename |
+| `document_list` | List all documents |
+| `contact_get` | Get a contact card by slug |
+| `contact_update` | Create or update a contact card |
+| `contact_list` | List all contact slugs |
+| `convention_list` | List conventions, optionally filtered by domain |
+| `convention_add` | Add a convention |
+| `convention_delete` | Delete a convention by ID |
+
+---
+
+## Personas
+
+| Preset | Character | Source |
+|--------|-----------|--------|
+| `natalie` | Natalie Teeger | Monk |
+| `donna` | Donna Paulsen | Suits |
+| `moneypenny` | Miss Moneypenny | James Bond |
+| `smithers` | Waylon Smithers | The Simpsons |
+| `april` | April Ludgate | Parks & Recreation |
+| `finch` | Dennis Finch | Just Shoot Me! |
+| `gary` | Gary Walsh | Veep |
+| `pam` | Pam Beesly | The Office |
+
+### Custom personas
+
+Drop a `.md` file in `<vault>/Natalie/personas/`:
+
+```markdown
+---
+name: My Assistant
+source: Original
+tone:
+  - helpful
+  - direct
+---
+
+Your persona prose here.
+```
+
+Then activate it:
+
+```bash
+natalie config --persona my-assistant
+```
+
+---
+
+## Configuration
+
+Edit `<vault>/Natalie/config.toml`, then run `natalie config --regen`:
+
+```toml
+[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
+bash /path/to/agent-natalie/install.sh
+```
+
+The script detects an existing install and offers to upgrade in place.
+
+---
+
+## Uninstall
+
+```bash
+bash /path/to/agent-natalie/uninstall.sh
+```

agent_natalie-0.1.0/install.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VENV_DIR="$HOME/.natalie/.venv"
+
+# ── uv ────────────────────────────────────────────────────────────────────────
+if ! command -v uv &>/dev/null; then
+    echo "Installing uv..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    [ -f "$HOME/.local/bin/env" ] && source "$HOME/.local/bin/env"
+    export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
+fi
+
+NATALIE="$VENV_DIR/bin/natalie"
+
+# ── Update detection ──────────────────────────────────────────────────────────
+if [[ -d "$VENV_DIR" ]]; then
+    echo "Existing Natalie install found at $VENV_DIR."
+    read -rp "Upgrade agent-natalie? [Y/n] " _UPGRADE
+    _UPGRADE="${_UPGRADE:-Y}"
+    if [[ "$_UPGRADE" =~ ^[Yy]$ ]]; then
+        echo "Upgrading agent-natalie..."
+        uv pip install --python "$VENV_DIR" --upgrade "$SCRIPT_DIR"
+        echo ""
+        echo "Done. Run 'natalie sync --full' from your vault directory to rebuild the search index."
+        exit 0
+    fi
+    echo "Proceeding with full re-install..."
+    rm -rf "$VENV_DIR"
+fi
+
+# ── Install agent-natalie ─────────────────────────────────────────────────────
+echo "Creating Python environment at $VENV_DIR..."
+mkdir -p "$HOME/.natalie"
+uv venv "$VENV_DIR"
+uv pip install --python "$VENV_DIR" "$SCRIPT_DIR"
+
+# ── Prompt for vault path ─────────────────────────────────────────────────────
+echo ""
+read -rp "Vault path (default: $HOME/Natalie): " VAULT_PATH
+VAULT_PATH="${VAULT_PATH:-$HOME/Natalie}"
+VAULT_PATH="${VAULT_PATH/#\~/$HOME}"
+
+# ── Prompt for persona ────────────────────────────────────────────────────────
+echo ""
+echo "Available personas: natalie, donna, moneypenny, smithers, april, finch, gary, pam"
+read -rp "Persona (default: natalie): " PERSONA
+PERSONA="${PERSONA:-natalie}"
+
+# ── Confirm vault modification ────────────────────────────────────────────────
+echo ""
+echo "natalie will create or modify the following in: $VAULT_PATH"
+echo "  Dashboard.md, CLAUDE.md, AGENTS.md   (skipped if already present)"
+echo "  .obsidian/snippets/                  (3 CSS files, skipped if already present)"
+echo "  .obsidian/appearance.json            (enables CSS snippets)"
+echo "  .mcp.json, .claude/settings.json, opencode.json, .opencode/hooks.json"
+echo ""
+read -rp "Proceed? [Y/n] " _PROCEED
+_PROCEED="${_PROCEED:-Y}"
+if [[ ! "$_PROCEED" =~ ^[Yy]$ ]]; then
+    echo "Aborted."
+    exit 1
+fi
+
+# ── Initialize vault ─────────────────────────────────────────────────────────
+echo ""
+echo "Initializing vault at $VAULT_PATH..."
+"$NATALIE" init "$VAULT_PATH" --persona "$PERSONA" --venv-path "$VENV_DIR"
+
+# ── Build initial index ───────────────────────────────────────────────────────
+echo ""
+echo "Building initial search index..."
+echo "On first run this downloads the embedding model (~130 MB)."
+echo "A progress bar will appear below — this may take several minutes on slow connections."
+echo ""
+cd "$VAULT_PATH"
+"$NATALIE" sync --full
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Done! Here's what to do next:"
+echo ""
+echo "  1. Open Obsidian and add '$VAULT_PATH' as a vault."
+echo "     The Dashboard layout and CSS snippets are pre-configured."
+echo "     If the multi-column layout doesn't appear, go to:"
+echo "       Settings → Appearance → CSS snippets"
+echo "     and make sure natalie-dashboard, MCL Multi Column, and MCL Wide Views"
+echo "     are toggled on. Then reload Obsidian (Cmd+R)."
+echo ""
+echo "  2. Install the Dataview community plugin (required for the Dashboard):"
+echo "       Settings → Community Plugins → turn off Safe Mode → Browse"
+echo "       Search 'Dataview' → Install → Enable"
+echo "     Then open Dataview settings and enable 'Enable JavaScript Queries'."
+echo ""
+echo "  3. Start Claude Code from inside the vault:"
+echo "       cd '$VAULT_PATH' && claude"
+echo "     Claude Code reads .mcp.json and connects to natalie-server automatically."
+echo "     The natalie tools (memory_search, note_write, task_list, …) will appear"
+echo "     in the tool list."
+echo ""
+echo "  4. Run 'natalie sync' from the vault directory any time you add new notes."
+echo "     (It runs automatically as a Claude Code hook after every tool use.)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"