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

Structure & Navigation

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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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.