io.github.hiveforge-sh/hivemind
MCP server for Obsidian vaults - AI tools with consistent canonical context. Local-first.
Hivemind for Obsidian
Your canon is the source of truth. AI stays inside the lines.
Why Hivemind?
When building fictional worlds — whether you're writing a novel, designing a game, or running an RPG campaign — AI tools can be powerful collaborators. But they hallucinate. Ask your AI assistant about a character you created last week, and it might invent details that contradict your established canon.
Hivemind solves this by giving AI tools structured access to your Obsidian vault. Think of it as an AI Firewall: your worldbuilding notes become a truth anchor that keeps AI grounded in facts you control. Ask about a character, and the AI reads your actual notes — not a hallucinated version. Query a timeline, and it references your established events — not invented dates.
Beyond AI integration, Hivemind provides powerful visualization tools:
- Timeline View — See your story's events laid out chronologically
- Graph View — Explore relationships between characters, locations, factions, and more
- Canon Workflow — Track which content is approved, in review, or still draft
Hivemind is built for worldbuilders, but the same principles apply to research vaults, people management, software architecture — anywhere you need AI to respect your established knowledge.
Features
- Timeline View — Visualize events chronologically with filtering and search
- Graph View — Explore entity relationships with interactive visualization
- AI Integration — MCP-compatible server for Claude, GitHub Copilot, and other AI tools
- Pluggable Templates — Built-in templates for worldbuilding, research, people management, and more
- Canon Workflow — Draft → Pending → Canon approval system with consistency validation
- Obsidian Native — Works with standard markdown, YAML frontmatter, and wikilinks
- Local-First — Your data stays on your machine
Built-in Templates
| Template | Use Case | Entity Types |
|---|---|---|
| Worldbuilding | Fiction writers, game designers, RPG creators | Characters, Locations, Events, Factions, Lore, Assets |
| Research | Academics, knowledge workers | Papers, Citations, Concepts, Notes |
| People Management | Managers, team leads | People, Goals, Teams, 1:1 Meetings |
| Software Architecture | Engineers, architects | Systems, Components, ADRs, Constraints |
Define your own custom entity types via config — no code required. See CONTRIBUTING_TEMPLATES.md for details.
Installation
Obsidian Plugin (Recommended)
- Open Obsidian Settings
- Go to Community plugins → Browse
- Search for "Hivemind"
- Click Install, then Enable
Manual Installation
- Download the latest release from GitHub Releases
- Extract to your vault's
.obsidian/plugins/hiveminddirectory - Reload Obsidian and enable the plugin in Settings
AI Integration (Optional)
Want AI tools to query your vault? Set up the MCP server:
The guide covers:
- Claude Desktop configuration (Windows, macOS, Linux)
- GitHub Copilot configuration
- Template selection
- Troubleshooting
Quick Start
-
Choose a template — Open Hivemind settings in Obsidian and select a template (worldbuilding, research, etc.)
-
Create entities — Use Obsidian's note creation as usual. Add YAML frontmatter to define entity types:
--- entity_type: character canon_status: draft --- -
Visualize — Open the Timeline view or Graph view from the ribbon icons
-
Connect to AI — Follow the MCP Setup Guide to let AI tools query your vault
For detailed setup instructions, see docs/SETUP_GUIDE.md.
Screenshots
Timeline View
Coming soon — chronological visualization of events
Graph View
Coming soon — interactive entity relationship visualization
Use Cases
Worldbuilding:
- Track characters, locations, and events across your novel
- AI remembers your character details when helping with dialogue
- Visualize timeline of your story's key events
Research:
- Organize papers, citations, and concepts in your field
- AI references your actual research when answering questions
- Explore connections between concepts in your knowledge base
People Management:
- Track team goals, 1:1 meeting notes, and people details
- AI recalls context from previous meetings when drafting agendas
- Visualize team relationships and reporting structures
Software Architecture:
- Document systems, components, and architectural decisions (ADRs)
- AI references your ADRs when suggesting design patterns
- Track dependencies between components visually
Documentation
- Setup Guide — Getting started with Hivemind
- MCP Setup Guide — AI integration configuration
- Vault Migration Guide — Migrating existing vaults
- Canon Workflow — Using canon workflow beyond worldbuilding
- Contributing Templates — Create and share templates
- Sample Vaults — Example vaults for each template
Community
- Issues & Feature Requests — GitHub Issues
- Discussions — GitHub Discussions
Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Important: This project uses Conventional Commits. Commit messages must follow the format:
<type>: <description>
[optional body]
Common types: feat, fix, docs, style, refactor, test, chore
License
MIT — Free for personal and commercial use.
Installation
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y @hiveforge/hivemind-mcpSet up in your AI client
Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-hiveforge-sh-hivemind": {
"command": "npx",
"args": [
"-y",
"@hiveforge/hivemind-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencePackage
@hiveforge/hivemind-mcpnpmCompatible MCP Clients
io.github.hiveforge-sh/hivemind works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
- Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect. - Cursor
~/.cursor/mcp.jsonRestart Cursor for changes to take effect. - VS Code
.vscode/mcp.jsonReload VS Code window for changes to take effect. - Windsurf
~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect. - Claude Code
.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.