# Obsidian Palace MCP
[](https://www.npmjs.com/package/obsidian-palace-mcp)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://nodejs.org)
[](https://github.com/sponsors/Probably-Computers)
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
```bash
npm install -g obsidian-palace-mcp
```
Or use directly with npx:
```bash
npx obsidian-palace-mcp
```
## Quick Start
### 1. Configure Claude Desktop / Claude Code
Add to your MCP client configuration:
**Single Vault (Quick Setup):**
```json
{
"mcpServers": {
"obsidian-palace": {
"command": "npx",
"args": ["obsidian-palace-mcp"],
"env": {
"PALACE_VAULTS": "/path/to/your/obsidian/vault:main:rw"
}
}
}
}
```
**Multi-Vault (Quick Setup):**
```json
{
"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):**
```json
{
"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:
```yaml
vault:
name: my-knowledge
description: "My knowledge base"
structure:
technology:
path: "technologies/{domain}/"
command:
path: "commands/{domain}/"
project:
path: "projects/{project}/"
```
See [Configuration Guide](docs/technical/CONFIGURATION.md) 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:
```javascript
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:
```yaml
---
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](docs/technical/API.md) - Complete tool documentation
- [Configuration Guide](docs/technical/CONFIGURATION.md) - All configuration options
- [AI Behavior Guide](docs/technical/AI-BEHAVIOR.md) - Protocols for AI assistants
- [Changelog](docs/technical/CHANGELOG.md) - Version history
## Development
```bash
# 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](docs/technical/CONTRIBUTING.md) for detailed guidelines.
## License
This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)** - see [LICENSE](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](LICENSE-COMMERCIAL.md) for options.
## Support the Project
If you find Obsidian Palace MCP useful, consider supporting its development:
- [GitHub Sponsors](https://github.com/sponsors/Probably-Computers) - Monthly sponsorship
- [Star the repo](https://github.com/Probably-Computers/obsidian-palace-mcp) - Help others discover it
- [Report issues](https://github.com/Probably-Computers/obsidian-palace-mcp/issues) - Help improve quality
## Credits
Built by [Probably Computers](https://probablycomputers.co.za)
Inspired by the Luci project's Memory Palace concept.
