@augmnt-sh/mindcache 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,227 @@
+<p align="center">
+  <h1 align="center">MindCache</h1>
+  <p align="center">Your Obsidian vault, connected to AI.</p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/mindcache"><img src="https://img.shields.io/npm/v/mindcache?color=8B5CF6&label=npm" alt="npm version"></a>
+  <a href="https://github.com/augmnt/mindcache/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-8B5CF6" alt="MIT License"></a>
+  <a href="https://github.com/augmnt/mindcache"><img src="https://img.shields.io/github/stars/augmnt/mindcache?color=8B5CF6" alt="GitHub stars"></a>
+</p>
+
+---
+
+MindCache is an open-source [MCP server](https://modelcontextprotocol.io) that bridges your Obsidian vault with AI assistants. Search, capture, and connect your personal knowledge — instantly.
+
+**40 tools** for finding, reading, writing, and organizing notes. Your AI can recall what you know, record what you learn, and connect ideas across your vault.
+
+## Quick Start
+
+### Prerequisites
+
+1. An [Obsidian](https://obsidian.md) vault (a folder of markdown files)
+2. Node.js 18+
+
+No plugins required. MindCache reads your vault directly from the filesystem.
+
+### Setup
+
+```bash
+# Interactive setup
+npx @augmnt-sh/mindcache init
+
+# Add to Claude Code
+claude mcp add --scope user mindcache -- npx @augmnt-sh/mindcache
+```
+
+That's it. Claude Code now has access to your vault.
+
+### Manual Configuration
+
+Create `~/.config/mindcache/config.yml`:
+
+```yaml
+vault: ~/Documents/Obsidian Vault
+
+daily_notes:
+  folder: Daily
+  format: YYYY-MM-DD
+
+templates:
+  folder: Templates/MindCache
+
+inbox:
+  folder: MindCache/Inbox
+  require_review: false
+```
+
+Or use environment variables:
+
+```bash
+export MINDCACHE_VAULT=~/Documents/Obsidian\ Vault
+```
+
+## Tools
+
+### Find (7)
+
+| Tool | Description |
+|------|-------------|
+| `search` | Full-text search with Obsidian operators |
+| `ask` | Natural language Q&A across your vault |
+| `find_related` | Notes connected via backlinks, tags, or content |
+| `find_by_tag` | Filter notes by tags |
+| `find_by_date` | Notes from a date range |
+| `find_recent` | Recently modified notes |
+| `find_mentions` | Where a term is mentioned |
+
+### Read (7)
+
+| Tool | Description |
+|------|-------------|
+| `read_note` | Full note content |
+| `read_section` | Content under a specific heading |
+| `read_summary` | Note with metadata (tags, links, word count) |
+| `read_properties` | YAML frontmatter only |
+| `read_today` | Today's daily note |
+| `read_this_week` | Daily notes from current week |
+| `get_active_note` | Currently open note in Obsidian |
+
+### Remember (7)
+
+| Tool | Description |
+|------|-------------|
+| `remember` | Quick capture to inbox |
+| `remember_meeting` | Structured meeting notes |
+| `remember_decision` | ADR-format decision log |
+| `remember_idea` | Capture an idea |
+| `remember_learning` | Save something learned |
+| `remember_person` | Person/contact note |
+| `remember_reference` | Bookmark with summary |
+
+### Journal (3)
+
+| Tool | Description |
+|------|-------------|
+| `log` | Append to daily note |
+| `log_task` | Add task to daily note |
+| `reflect` | Reflection prompts |
+
+### Write (3)
+
+| Tool | Description |
+|------|-------------|
+| `create_note` | Create note with optional template |
+| `append_to_note` | Append to existing note |
+| `update_section` | Replace section content |
+
+### Connect (4)
+
+| Tool | Description |
+|------|-------------|
+| `add_link` | Insert wikilink between notes |
+| `suggest_connections` | AI-powered link suggestions |
+| `find_gaps` | Broken links (knowledge gaps) |
+| `find_orphans` | Disconnected notes |
+
+### Organize (4)
+
+| Tool | Description |
+|------|-------------|
+| `add_tag` | Add tags to a note |
+| `update_properties` | Modify frontmatter |
+| `rename_note` | Rename a note |
+| `move_note` | Move to different folder |
+
+### Understand (3)
+
+| Tool | Description |
+|------|-------------|
+| `vault_overview` | Stats, folders, tags |
+| `list_tags` | All tags with counts |
+| `get_vault_structure` | Folder tree |
+
+### Tasks (2)
+
+| Tool | Description |
+|------|-------------|
+| `find_tasks` | Find checkbox tasks |
+| `complete_task` | Mark task as done |
+
+## Resources
+
+MindCache also exposes MCP resources for automatic context:
+
+| Resource | Description |
+|----------|-------------|
+| `vault://today` | Today's daily note |
+| `vault://recent` | Recently modified notes |
+| `vault://tags` | Tag cloud |
+| `vault://context` | Project-relevant notes |
+
+## Templates
+
+MindCache ships with 10 note templates: `decision`, `meeting`, `learning`, `idea`, `person`, `project`, `book`, `article`, `weekly-review`, `session`.
+
+## CLI
+
+```bash
+npx @augmnt-sh/mindcache              # Start MCP server
+npx @augmnt-sh/mindcache init          # Interactive setup
+npx @augmnt-sh/mindcache doctor        # Diagnose issues
+npx @augmnt-sh/mindcache config        # Show configuration
+npx @augmnt-sh/mindcache --help        # Help
+npx @augmnt-sh/mindcache --version     # Version
+```
+
+## MCP Client Configuration
+
+### Claude Code
+
+```bash
+claude mcp add --scope user mindcache -- npx @augmnt-sh/mindcache
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mindcache": {
+      "command": "npx",
+      "args": ["@augmnt-sh/mindcache"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to MCP settings:
+
+```json
+{
+  "mindcache": {
+    "command": "npx",
+    "args": ["@augmnt-sh/mindcache"]
+  }
+}
+```
+
+## Privacy
+
+MindCache runs entirely on your machine. Your notes never leave your computer. No cloud, no accounts, no telemetry.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.
+
+---
+
+Built by [augmnt](https://augmnt.sh) | [Website](https://usemindcache.com) | [npm](https://www.npmjs.com/package/mindcache)