Obsidian Palace MCP

An MCP server that turns your Obsidian vault into an AI memory palace.

What is this?

Obsidian Palace MCP enables AI assistants (Claude, ChatGPT, or any MCP-compatible client) to use your Obsidian vault as a persistent memory store. The AI can:

Store knowledge using intent-based storage (AI says WHAT, Palace decides WHERE)
Retrieve information using full-text search or structured queries
Auto-link notes by detecting mentions of existing note titles
Check before storing to prevent duplicates and expand existing knowledge
Query with Dataview using familiar DQL syntax
Follow standards defined in your vault
Track provenance - know where every piece of knowledge came from

v2.0 Features

Feature	Description
🧠 Intent-Based Storage	AI expresses intent; Palace resolves location
📚 Multi-Vault Support	Multiple vaults with read/write access control
⚛️ Atomic Notes	Auto-splitting large content into hub + children
📋 Standards System	AI follows user-defined binding standards
🔗 Auto-Linking	Automatically creates `[[wiki-links]]` between related notes
📊 Dataview Queries	Query your vault using DQL syntax
📍 Provenance	Track source, confidence, and verification status
🤖 AI-Agnostic	Works with any MCP-compatible client
⚡ Fast Search	SQLite FTS5 full-text search index
👁️ Live Sync	Watches for external changes to your vault
❓ Context Clarification	AI asks for missing context before storing

Installation

npm install -g obsidian-palace-mcp

Or use directly with npx:

npx obsidian-palace-mcp

Quick Start

1. Configure Claude Desktop / Claude Code

Add to your MCP client configuration:

Single Vault (Quick Setup):

{
  "mcpServers": {
    "obsidian-palace": {
      "command": "npx",
      "args": ["obsidian-palace-mcp"],
      "env": {
        "PALACE_VAULTS": "/path/to/your/obsidian/vault:main:rw"
      }
    }
  }
}

Multi-Vault (Quick Setup):

{
  "mcpServers": {
    "obsidian-palace": {
      "command": "npx",
      "args": ["obsidian-palace-mcp"],
      "env": {
        "PALACE_VAULTS": "/path/to/work:work:rw,/path/to/personal:personal:rw",
        "PALACE_DEFAULT_VAULT": "work"
      }
    }
  }
}

Multi-Vault (Config File):

{
  "mcpServers": {
    "obsidian-palace": {
      "command": "npx",
      "args": ["obsidian-palace-mcp"],
      "env": {
        "PALACE_CONFIG_PATH": "~/.config/palace/config.yaml"
      }
    }
  }
}

2. Create a Vault Config (Optional)

Create .palace.yaml in your vault root for custom structure mapping:

vault:
  name: my-knowledge
  description: "My knowledge base"

structure:
  technology:
    path: "technologies/{domain}/"
  command:
    path: "commands/{domain}/"
  project:
    path: "projects/{project}/"

See Configuration Guide for full options.

Tools

Core Tools

Tool	Description
`palace_store`	Store knowledge with intent-based resolution
`palace_check`	Check for existing knowledge before storing
`palace_read`	Read a specific note
`palace_improve`	Update existing notes intelligently
`palace_recall`	Search the vault for information

Tool	Description
`palace_list`	List notes in a directory
`palace_structure`	Get vault directory tree
`palace_vaults`	List configured vaults

Graph Intelligence

Tool	Description
`palace_links`	Get backlinks and outgoing links
`palace_orphans`	Find notes with no connections
`palace_related`	Find related notes
`palace_autolink`	Scan vault and create wiki-links

Queries

Tool	Description
`palace_dataview`	Execute Dataview (DQL) queries
`palace_query`	Property-based queries

Standards & AI Support

Tool	Description
`palace_standards`	Load binding standards for AI
`palace_standards_validate`	Validate notes against standards
`palace_clarify`	Generate clarifying questions for incomplete context

Sessions

Tool	Description
`palace_session_start`	Start a research session
`palace_session_log`	Log activity to current session

Knowledge Organization

Knowledge Layers

Palace organizes knowledge into three layers:

Layer 1: Technical (never project-specific)

technologies/ - Technology documentation
commands/ - CLI commands and scripts
reference/ - Quick references

Layer 2: Domain (reusable knowledge)

standards/ - Standards and conventions
patterns/ - Reusable patterns
research/ - Research findings

Layer 3: Contextual (project/client specific)

projects/ - Project decisions and configs
clients/ - Client-specific knowledge

Intent-Based Storage

AI expresses WHAT to store; Palace determines WHERE:

palace_store({
  title: "Docker Bridge Networking",
  content: "...",
  intent: {
    knowledge_type: "command",
    domain: ["docker", "networking"],
    scope: "general"
  }
})
// Resolves to: commands/docker/networking/docker-bridge-networking.md

Atomic Notes

Large content is automatically split into hub + atomic notes:

Max 200 lines per atomic note
Max 6 H2 sections per note
Hub notes (_index.md) provide navigation

Note Format

Notes use YAML frontmatter for metadata:

---
type: technology
status: active
domain: [kubernetes, networking]
source:
  origin: ai:research
  confidence: 0.8
  verified: false
tags: [kubernetes, networking]
created: 2025-12-05T14:30:00Z
modified: 2025-12-05T14:30:00Z
---

# Kubernetes Networking

Content here...

Knowledge Types

Type	Layer	Purpose
`technology`	1	Technology documentation
`command`	1	CLI commands and snippets
`reference`	1	Quick reference material
`standard`	2	Standards and conventions
`pattern`	2	Reusable patterns
`research`	2	Research findings
`decision`	3	Project decisions
`configuration`	3	Project-specific configs
`troubleshooting`	1-2	Problems and solutions
`note`	varies	General notes

Example Usage

Storing Knowledge (v2.0 way)

AI: "I'll document this Docker networking command."

[Uses palace_check to verify no existing note]
[Uses palace_store with:
  - knowledge_type: "command"
  - domain: ["docker", "networking"]
  - scope: "general"
  - technologies: ["docker"]
]

Finding Information

User: "What do we know about setting up Tailscale?"

AI: [Uses palace_recall with query: "tailscale setup"]
    [Uses palace_related to find connected topics]
    "Based on your notes, here's what we have..."

Following Standards

AI starts session:
[Uses palace_standards({ binding: 'required' })]
[Acknowledges standards before proceeding]

User: "Help me with a git commit"
AI: [Follows git workflow standard from vault]

Environment Variables

Variable	Required	Default	Description
`PALACE_VAULTS`	Yes*	-	Vault config: `path:alias:mode,...`
`PALACE_CONFIG_PATH`	No	`~/.config/palace/config.yaml`	Global config file
`PALACE_DEFAULT_VAULT`	No	First vault	Default vault alias
`PALACE_LOG_LEVEL`	No	`info`	debug, info, warn, error
`PALACE_WATCH_ENABLED`	No	`true`	Watch for file changes

*Required unless PALACE_CONFIG_PATH is set pointing to a config file.

Troubleshooting

Server won't start

"PALACE_VAULTS is required"

Ensure you've set PALACE_VAULTS in your MCP client config or use PALACE_CONFIG_PATH
Format: path:alias:mode (e.g., /path/to/vault:main:rw)

"Cannot find module 'better-sqlite3'"

Run npm rebuild better-sqlite3 if you installed globally
This native module may need recompilation for your Node version

Notes not appearing

Check vault path

Verify the path in PALACE_VAULTS points to your actual Obsidian vault
The path should contain .obsidian/ folder

Check ignore patterns

Files in .obsidian/, templates/, or directories with .palace-ignore are skipped
Notes with palace_ignore: true in frontmatter are also skipped

Search not finding notes

Rebuild the index

Delete .palace/index.sqlite in your vault and restart the server
The index will be rebuilt automatically on startup

Permission errors

Read-only vault

Check the mode in PALACE_VAULTS - use :rw for read-write, :ro for read-only
Verify file system permissions on the vault directory

Documentation

API Reference - Complete tool documentation
Configuration Guide - All configuration options
AI Behavior Guide - Protocols for AI assistants
Changelog - Version history

Development

# Clone the repository
git clone https://github.com/Probably-Computers/obsidian-palace-mcp.git
cd obsidian-palace-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see LICENSE for details.

Commercial Use

If you need to use Obsidian Palace MCP in proprietary software or as part of a commercial SaaS without open-sourcing your modifications, commercial licenses are available. See LICENSE-COMMERCIAL.md for options.

Support the Project

If you find Obsidian Palace MCP useful, consider supporting its development:

GitHub Sponsors - Monthly sponsorship
Star the repo - Help others discover it
Report issues - Help improve quality

Credits

Built by Probably Computers

Inspired by the Luci project's Memory Palace concept.

Obsidian Palace MCP

An MCP server that turns your Obsidian vault into an AI memory palace.

What is this?

Obsidian Palace MCP enables AI assistants (Claude, ChatGPT, or any MCP-compatible client) to use your Obsidian vault as a persistent memory store. The AI can:

Store knowledge using intent-based storage (AI says WHAT, Palace decides WHERE)
Retrieve information using full-text search or structured queries
Auto-link notes by detecting mentions of existing note titles
Check before storing to prevent duplicates and expand existing knowledge
Query with Dataview using familiar DQL syntax
Follow standards defined in your vault
Track provenance - know where every piece of knowledge came from

v2.0 Features

Feature	Description
🧠 Intent-Based Storage	AI expresses intent; Palace resolves location
📚 Multi-Vault Support	Multiple vaults with read/write access control
⚛️ Atomic Notes	Auto-splitting large content into hub + children
📋 Standards System	AI follows user-defined binding standards
🔗 Auto-Linking	Automatically creates `[[wiki-links]]` between related notes
📊 Dataview Queries	Query your vault using DQL syntax
📍 Provenance	Track source, confidence, and verification status
🤖 AI-Agnostic	Works with any MCP-compatible client
⚡ Fast Search	SQLite FTS5 full-text search index
👁️ Live Sync	Watches for external changes to your vault
❓ Context Clarification	AI asks for missing context before storing

Installation

npm install -g obsidian-palace-mcp

Or use directly with npx:

npx obsidian-palace-mcp

Quick Start

1. Configure Claude Desktop / Claude Code

Add to your MCP client configuration:

Single Vault (Quick Setup):

{
  "mcpServers": {
    "obsidian-palace": {
      "command": "npx",
      "args": ["obsidian-palace-mcp"],
      "env": {
        "PALACE_VAULTS": "/path/to/your/obsidian/vault:main:rw"
      }
    }
  }
}

Multi-Vault (Quick Setup):

{
  "mcpServers": {
    "obsidian-palace": {
      "command": "npx",
      "args": ["obsidian-palace-mcp"],
      "env": {
        "PALACE_VAULTS": "/path/to/work:work:rw,/path/to/personal:personal:rw",
        "PALACE_DEFAULT_VAULT": "work"
      }
    }
  }
}

Multi-Vault (Config File):

{
  "mcpServers": {
    "obsidian-palace": {
      "command": "npx",
      "args": ["obsidian-palace-mcp"],
      "env": {
        "PALACE_CONFIG_PATH": "~/.config/palace/config.yaml"
      }
    }
  }
}

2. Create a Vault Config (Optional)

Create .palace.yaml in your vault root for custom structure mapping:

vault:
  name: my-knowledge
  description: "My knowledge base"

structure:
  technology:
    path: "technologies/{domain}/"
  command:
    path: "commands/{domain}/"
  project:
    path: "projects/{project}/"

See Configuration Guide for full options.

Tools

Core Tools

Tool	Description
`palace_store`	Store knowledge with intent-based resolution
`palace_check`	Check for existing knowledge before storing
`palace_read`	Read a specific note
`palace_improve`	Update existing notes intelligently
`palace_recall`	Search the vault for information

Tool	Description
`palace_list`	List notes in a directory
`palace_structure`	Get vault directory tree
`palace_vaults`	List configured vaults

Graph Intelligence

Tool	Description
`palace_links`	Get backlinks and outgoing links
`palace_orphans`	Find notes with no connections
`palace_related`	Find related notes
`palace_autolink`	Scan vault and create wiki-links

Queries

Tool	Description
`palace_dataview`	Execute Dataview (DQL) queries
`palace_query`	Property-based queries

Standards & AI Support

Tool	Description
`palace_standards`	Load binding standards for AI
`palace_standards_validate`	Validate notes against standards
`palace_clarify`	Generate clarifying questions for incomplete context

Sessions

Tool	Description
`palace_session_start`	Start a research session
`palace_session_log`	Log activity to current session

Knowledge Organization

Knowledge Layers

Palace organizes knowledge into three layers:

Layer 1: Technical (never project-specific)

technologies/ - Technology documentation
commands/ - CLI commands and scripts
reference/ - Quick references

Layer 2: Domain (reusable knowledge)

standards/ - Standards and conventions
patterns/ - Reusable patterns
research/ - Research findings

Layer 3: Contextual (project/client specific)

projects/ - Project decisions and configs
clients/ - Client-specific knowledge

Intent-Based Storage

AI expresses WHAT to store; Palace determines WHERE:

palace_store({
  title: "Docker Bridge Networking",
  content: "...",
  intent: {
    knowledge_type: "command",
    domain: ["docker", "networking"],
    scope: "general"
  }
})
// Resolves to: commands/docker/networking/docker-bridge-networking.md

Atomic Notes

Large content is automatically split into hub + atomic notes:

Max 200 lines per atomic note
Max 6 H2 sections per note
Hub notes (_index.md) provide navigation

Note Format

Notes use YAML frontmatter for metadata:

---
type: technology
status: active
domain: [kubernetes, networking]
source:
  origin: ai:research
  confidence: 0.8
  verified: false
tags: [kubernetes, networking]
created: 2025-12-05T14:30:00Z
modified: 2025-12-05T14:30:00Z
---

# Kubernetes Networking

Content here...

Knowledge Types

Type	Layer	Purpose
`technology`	1	Technology documentation
`command`	1	CLI commands and snippets
`reference`	1	Quick reference material
`standard`	2	Standards and conventions
`pattern`	2	Reusable patterns
`research`	2	Research findings
`decision`	3	Project decisions
`configuration`	3	Project-specific configs
`troubleshooting`	1-2	Problems and solutions
`note`	varies	General notes

Example Usage

Storing Knowledge (v2.0 way)

AI: "I'll document this Docker networking command."

[Uses palace_check to verify no existing note]
[Uses palace_store with:
  - knowledge_type: "command"
  - domain: ["docker", "networking"]
  - scope: "general"
  - technologies: ["docker"]
]

Finding Information

User: "What do we know about setting up Tailscale?"

AI: [Uses palace_recall with query: "tailscale setup"]
    [Uses palace_related to find connected topics]
    "Based on your notes, here's what we have..."

Following Standards

AI starts session:
[Uses palace_standards({ binding: 'required' })]
[Acknowledges standards before proceeding]

User: "Help me with a git commit"
AI: [Follows git workflow standard from vault]

Environment Variables

Variable	Required	Default	Description
`PALACE_VAULTS`	Yes*	-	Vault config: `path:alias:mode,...`
`PALACE_CONFIG_PATH`	No	`~/.config/palace/config.yaml`	Global config file
`PALACE_DEFAULT_VAULT`	No	First vault	Default vault alias
`PALACE_LOG_LEVEL`	No	`info`	debug, info, warn, error
`PALACE_WATCH_ENABLED`	No	`true`	Watch for file changes

*Required unless PALACE_CONFIG_PATH is set pointing to a config file.

Troubleshooting

Server won't start

"PALACE_VAULTS is required"

Ensure you've set PALACE_VAULTS in your MCP client config or use PALACE_CONFIG_PATH
Format: path:alias:mode (e.g., /path/to/vault:main:rw)

"Cannot find module 'better-sqlite3'"

Run npm rebuild better-sqlite3 if you installed globally
This native module may need recompilation for your Node version

Notes not appearing

Check vault path

Verify the path in PALACE_VAULTS points to your actual Obsidian vault
The path should contain .obsidian/ folder

Check ignore patterns

Files in .obsidian/, templates/, or directories with .palace-ignore are skipped
Notes with palace_ignore: true in frontmatter are also skipped

Search not finding notes

Rebuild the index

Delete .palace/index.sqlite in your vault and restart the server
The index will be rebuilt automatically on startup

Permission errors

Read-only vault

Check the mode in PALACE_VAULTS - use :rw for read-write, :ro for read-only
Verify file system permissions on the vault directory

Documentation

API Reference - Complete tool documentation
Configuration Guide - All configuration options
AI Behavior Guide - Protocols for AI assistants
Changelog - Version history

Development

# Clone the repository
git clone https://github.com/Probably-Computers/obsidian-palace-mcp.git
cd obsidian-palace-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see LICENSE for details.

Commercial Use

Support the Project

If you find Obsidian Palace MCP useful, consider supporting its development:

GitHub Sponsors - Monthly sponsorship
Star the repo - Help others discover it
Report issues - Help improve quality

Credits

Built by Probably Computers

Inspired by the Luci project's Memory Palace concept.

Obsidian Palace MCP

Obsidian Palace MCP

What is this?

v2.0 Features

Installation

Quick Start

1. Configure Claude Desktop / Claude Code

2. Create a Vault Config (Optional)

Tools

Core Tools

Structure & Navigation

Graph Intelligence

Queries

Standards & AI Support

Sessions

Knowledge Organization

Knowledge Layers

Intent-Based Storage

Atomic Notes

Note Format

Knowledge Types

Example Usage

Storing Knowledge (v2.0 way)

Finding Information

Following Standards

Environment Variables

Troubleshooting

Server won't start

Notes not appearing

Search not finding notes

Permission errors

Documentation

Development

Contributing

License

Commercial Use

Support the Project

Credits

Obsidian Palace MCP

What is this?

v2.0 Features

Installation

Quick Start

1. Configure Claude Desktop / Claude Code

2. Create a Vault Config (Optional)

Tools

Core Tools

Structure & Navigation

Graph Intelligence

Queries

Standards & AI Support

Sessions

Knowledge Organization

Knowledge Layers

Intent-Based Storage

Atomic Notes

Note Format

Knowledge Types

Example Usage

Storing Knowledge (v2.0 way)

Finding Information

Following Standards

Environment Variables

Troubleshooting

Server won't start

Notes not appearing

Search not finding notes

Permission errors

Documentation

Development

Contributing

License

Commercial Use

Support the Project

Credits