obsidian-agent-tools

Cross-harness tools for using an Obsidian vault from agent runtimes. The package provides an MCP server for notebook operations and shared local session summarization for Claude Code and Pi.

Prerequisites

• Obsidian with CLI support (v1.8+, macOS)
• Node.js >=18
• Ollama
• Claude Code and/or Pi, if lifecycle summaries are desired

Configuration

Variable	Default	Description
OBSIDIAN_VAULT	$HOME/obsidian-git-sync	Absolute Obsidian vault path used by the MCP server
OBSIDIAN_VAULT_NAME	obsidian-git-sync	Registered Obsidian CLI vault name; required for unambiguous CLI operations
OBSIDIAN_VAULT_PATH	$OBSIDIAN_VAULT	Optional filesystem path for CLI-local tooling; does not select the CLI vault
OBSIDIAN_DATA_DIR	$HOME/.local/share/obsidian-agent-tools	SQLite database and summarizer logs
OBSIDIAN_CLI_PATH	/Applications/Obsidian.app/Contents/MacOS/obsidian	Obsidian CLI binary
OLLAMA_HOST	http://127.0.0.1:11434	Local Ollama endpoint
OBSIDIAN_SUMMARY_MODEL	qwen2.5:7b	Local model used for session summaries
OBSIDIAN_AGENT_SUMMARIZER	package-local in Pi; repository launcher otherwise	Override the shared summarizer executable
OBSIDIAN_MEMORY_ENABLED	enabled	Set to 0 to disable automatic memory-context injection
OBSIDIAN_MEMORY_TIMEOUT_MS	5000	Maximum time Pi and Claude hooks wait for memory retrieval
OBSIDIAN_MEMORY_MAX_CHARS	2000	Rendered-character budget for injected memory context
OBSIDIAN_MEMORY_MAX_RESULTS	1	Maximum confirmed durable-memory candidate
OBSIDIAN_MEMORY_PROJECT_RESULTS	1	Maximum current-project candidate
OBSIDIAN_MEMORY_BROAD_RESULTS	0	Broad-vault candidates; set above zero to opt in for explicit recall prompts
OBSIDIAN_AGENT_CONTEXT	package-local in Pi; $HOME/.local/bin/obsidian-agent-context otherwise	Override the shared retrieval executable used by Pi and Claude hooks
OBSIDIAN_MEMORY_DURABLE_DIR	3_Resource/agent memory/	Vault-relative prefix for durable agent-memory notes
OBSIDIAN_PROJECTS_DIR	1_Projects	Vault-relative prefix for project notes; used for project-scoped retrieval
OBSIDIAN_VAULT_SECTIONS	1_Projects/,2_Areas/,3_Resource/,4_Archive/	Comma-separated vault-relative prefixes searched during broad retrieval; set to empty string to search the whole vault
OBSIDIAN_SESSIONS_DIR	4_Archive/_agent_sessions	Vault-relative directory where session summaries are written

Session summaries are generated locally. Transcripts are not sent to Vertex AI or another remote provider.

Build and test

npm install
npm run build
npm test

Install the local model once, or let the summarizer pull it when the first session ends:

ollama pull qwen2.5:7b

MCP server

Automated setup (Claude Code)

Run the installer to build, register the MCP server, and symlink all three hooks in one step:

./scripts/install-claude-hooks.sh

Options:

Flag	Description
--vault PATH	Vault path (defaults to OBSIDIAN_VAULT env var or ~/obsidian-git-sync)
--no-mcp	Skip MCP server registration
--no-models	Skip Ollama model pulls
--dry-run	Print what would be done without making changes

The script detects existing hook files, backs them up, and reports what it did. Restart Claude Code after running it.

Manual setup

Register the MCP server with Claude Code or another MCP client:

npm run build
claude mcp add obsidian -s user \
  -e OBSIDIAN_VAULT=/absolute/path/to/your/vault \
  -e OBSIDIAN_CLI_PATH=/Applications/Obsidian.app/Contents/MacOS/obsidian \
  -- node /absolute/path/to/obsidian-agent-tools/dist/index.js

The MCP server provides vault information, note read/write/manage operations, search, graph navigation, tags, aliases, properties, tasks, session context, and searchable session summaries.

Agent memory skill

This repository also packages the autonomous agent-memory skill. It stores durable corrections, preferences, and reusable failure/workaround patterns as individual notes under:

$OBSIDIAN_VAULT/3_Resource/agent memory/

The skill prefers the obsidian-agent-tools MCP server when available. In Pi, where MCP is not used, it falls back to the Obsidian CLI through Bash. Set OBSIDIAN_VAULT_NAME to the registered vault name for CLI operations; OBSIDIAN_VAULT is the filesystem path used by the MCP server. The skill passes vault=... explicitly and reads notes back after every write before reporting success.

Install with Lola

Register this repository as a Lola module, then install its skills for Claude Code at user scope:

lola mod add https://github.com/Marcusk19/obsidian-agent-tools.git \\
  --name obsidian-agent-tools
lola install obsidian-agent-tools \\
  --assistant claude-code \\
  --scope user \\
  --force \\
  --append-context module/AGENTS.md

The module contains a short dispatcher at module/skills/agent-memory/SKILL.md, operation-specific instructions under its references/ directory, and always-on instructions at module/AGENTS.md. Detailed capture, lifecycle, formatting, and CLI guidance is loaded only when needed. --append-context installs the module instructions without replacing the rest of the assistant's global context. If the module was previously registered, update it before reinstalling:

lola mod update obsidian-agent-tools
lola install obsidian-agent-tools --assistant claude-code --scope user --force \\
  --append-context module/AGENTS.md

Lola currently lists Claude Code, Cursor, Gemini CLI, OpenClaw, and OpenCode as installation targets; Pi uses its native package support instead:

pi install npm:obsidian-agent-tools
# Or pin an unpublished Git revision:
pi install git:github.com/Marcusk19/obsidian-agent-tools@<commit-or-tag>

This installs both the Pi extension and the agent-memory skill. The extension uses the package-local context and summarizer launchers, so no global npm install or manual copy into ~/.agents/skills is needed. To test an unpublished local checkout, use pi install /absolute/path/to/obsidian-agent-tools after running npm install && npm run build in the checkout.

Pi uses the CLI fallback documented in the skill because no MCP server is required. After installation, run the bootstrap command once to pull the embedding model and create or rebuild the local vector index:

/obsidian-bootstrap

The command requires Ollama to be installed and running. It skips the model pull when nomic-embed-text is already present, then rebuilds $OBSIDIAN_DATA_DIR/vault-index.db from the configured vault.

Automatic memory context

obsidian-agent-context is the single hot-path interface for memory retrieval before each agent turn. It uses the local lexical index without waiting for Ollama or semantic embeddings, searches active scope-matching durable memory first, optionally checks only the project identified by cwd/repository metadata, and does not search broad vault context by default. Broad search requires both an explicit recall prompt and OBSIDIAN_MEMORY_BROAD_RESULTS above zero.

The command injects at most one confirmed durable rule and one scoped project excerpt by default. Durable excerpts prefer ## Rule plus a short ## Applies when summary, always include the source path, and omit internal ranking metadata. Output stays under OBSIDIAN_MEMORY_MAX_CHARS (default 2,000 UTF-8 characters). A miss returns an empty string.

obsidian-agent-context [--cwd PATH] [--repository NAME] [--project NAME] <prompt>

Automatic injection satisfies routine start-of-task memory retrieval; agents should not load the full skill or repeat the search on every turn. The compact rule excerpt is enough for low-risk guidance. Open the canonical source note only when exact commands, exceptions, conflicts, rationale, or consequential actions depend on it, or when explicit history/notes retrieval requires escalation. Retrieval errors never block the prompt. Hooks wait up to five seconds by default; set OBSIDIAN_MEMORY_TIMEOUT_MS to tune that limit. Deeper manual searches still use semantic retrieval when available. Set OBSIDIAN_MEMORY_ENABLED=0 to opt out without removing the installed hooks.

Pi

integrations/pi/obsidian-agent-tools.ts now invokes obsidian-agent-context before each agent turn. The extension passes the turn prompt and Pi’s current working directory to the shared executable and injects the rendered Markdown as an invisible customType: "obsidian-memory" message. Override the executable path with OBSIDIAN_AGENT_CONTEXT if the command is installed somewhere other than $HOME/.local/bin/obsidian-agent-context.

Claude Code

Install integrations/claude-code/on-user-prompt-submit as Claude Code’s on_user_prompt_submit hook alongside the existing on-session-end and on-post-compact hooks:

ln -sf /path/to/obsidian-agent-tools/integrations/claude-code/on-user-prompt-submit \
  "$HOME/Library/Application Support/Claude/hooks/on-user-prompt-submit"

The hook reads Claude’s JSON payload from stdin, launches obsidian-agent-context with the prompt and cwd, and writes a JSON response that preserves the original prompt plus a system_context field when results are available. Claude only sees the injected Markdown; the hook does not store prompts, retrieved context, or secrets in the vault.

Shared session summaries

Both runtimes write new summaries to:

$OBSIDIAN_VAULT/4_Archive/_agent_sessions/YYYY-MM-DD.md

Existing _claude_sessions and _pi_sessions files are intentionally left in place.

Entries use the same format for both runtimes:

### 10:32 — Improve session summarization

The session summary is a concise plain-prose handoff.

**Runtime:** `pi`
**Session:** `abc123`
**CWD:** `~/workspace/project`

Claude Code

Configure the SessionEnd hook to invoke integrations/claude-code/on-session-end. The hook reads Claude's hook JSON, normalizes the transcript, and launches the shared summarizer without blocking shutdown. The PostCompact hook is available at integrations/claude-code/on-post-compact, and integrations/claude-code/on-user-prompt-submit injects automatic memory context on on_user_prompt_submit before Claude runs the prompt.

Set OBSIDIAN_AGENT_SUMMARIZER to the absolute path of bin/obsidian-agent-summarize when the hook is installed outside this checkout.

Pi

Install the package with pi install npm:obsidian-agent-tools, or test a pinned revision with pi install git:github.com/Marcusk19/obsidian-agent-tools@<commit-or-tag>. Pi loads integrations/pi/obsidian-agent-tools.ts automatically. The extension summarizes only actual quit events and runs the package-local shared process detached. OBSIDIAN_AGENT_SUMMARIZER remains available as an explicit executable override.

Search

The vault is semantically indexed in a disposable SQLite database at:

$OBSIDIAN_DATA_DIR/vault-index.db

The index covers every Markdown note, including generated session summaries. Markdown files remain the source of truth and the index is refreshed lazily when searching. Notes are split on Markdown headings into approximately 400-token chunks with 80-token overlap; results retain their heading and source line range. The fixed Ollama model nomic-embed-text supplies 768-dimensional embeddings.

Set up the vault index

The index database is local derived state. It is created automatically on the first routed search and is not stored in the vault or synchronized through Git.

From a checkout of this repository:

cd /absolute/path/to/obsidian-agent-tools
pnpm install
pnpm build
pnpm add --global /absolute/path/to/obsidian-agent-tools

Install the embedding model in Ollama:

ollama pull nomic-embed-text

Set the vault and data directory when using the CLI:

export OBSIDIAN_VAULT="$HOME/obsidian-git-sync"
export OBSIDIAN_DATA_DIR="$HOME/.local/share/obsidian-agent-tools"

Build the initial index with a semantic search:

obsidian-agent-search vault "search your notes"

To discard and recreate the derived index from the current Markdown files:

obsidian-agent-search vault --rebuild "search your notes"

The rebuild scans all Markdown files, including 4_Archive/_agent_sessions/. It does not migrate or modify the legacy summaries.db. The derived index records a fingerprint of its schema, embedding model and dimensions, chunking version, and source pattern; a mismatch automatically invalidates old rows so they can be rebuilt from Markdown. If Ollama is unavailable, keyword indexing and search still work, but semantic results are unavailable until embeddings can be generated.

Use hybrid vault search through MCP:

obsidian_search_vault(query="explicit vault selector")

Or from Pi/non-MCP runtimes:

obsidian-agent-search vault "explicit vault selector"
obsidian-agent-search vault --rebuild "explicit vault selector"

Search runs BM25 keyword retrieval and vector retrieval independently, merges their union with weighted component scores, and adds bounded path/title/heading boosts. The best matching chunk per note is returned with its heading and line range. Keyword-backed results are marked confirmed; semantic-only results are retained with lower confidence. If Ollama is unavailable, keyword search continues to work. Automatic pre-turn memory injection deliberately remains lexical-only for predictable latency.

The older summaries.db is a legacy session-summary index and is not used by the vault search path. New session summaries are indexed from their Markdown files during the next vault search.

Migration from claude-obsidian

This project is the generalized successor to claude-obsidian. The old repository is being archived. There are no old package-name or old environment-variable compatibility aliases in this project. Existing _claude_sessions and _pi_sessions directories are not moved or copied.

License

MIT