@augmnt-sh/mindcache 0.1.0 → 0.1.1

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)

package/dist/cli.js

@@ -191,7 +191,7 @@ Relevant vault notes:
 ${i}`,mimeType:"text/markdown"}]}}catch{return {contents:[{uri:t.href,text:"Could not determine context.",mimeType:"text/plain"}]}}});}var z="mindcache";function k(s){process.stderr.write(`[${z}] ${s}
 `);}function P(s){process.stderr.write(`[${z}] ERROR: ${s}
 `);}function ut(s){process.stderr.write(`[${z}] WARN: ${s}
-`);}var F="0.1.0";function pt(s){let n=new McpServer({name:"mindcache",version:F},{instructions:["MindCache connects your Obsidian vault to AI.","Use the search and ask tools to find information in the user's personal knowledge base.","Use the remember tools to capture decisions, meetings, ideas, learnings, and references.","Use the log tool to add entries to the daily note.","Use the connect tools to build links between related notes.","Always check the vault before asking the user to repeat information they may have already documented.","When creating notes, use appropriate templates and add relevant tags."].join(" ")}),c=new M(s);return k("Registering tools..."),et(n,c),nt(n,c,s),rt(n,c,s),st(n,c,s),it(n,c),at(n,c),ct(n,c),lt(n,c),dt(n,c),k("Registering resources..."),ft(n,c,s),k("Server configured with 40 tools and 4 resources"),n}var Y={vault:"",dailyNotes:{folder:"Daily",format:"YYYY-MM-DD"},templates:{folder:"Templates/MindCache"},inbox:{folder:"MindCache/Inbox",requireReview:false}};function Ot(s){let n={},c="";for(let t of s.split(`
+`);}var F="0.1.1";function pt(s){let n=new McpServer({name:"mindcache",version:F},{instructions:["MindCache connects your Obsidian vault to AI.","Use the search and ask tools to find information in the user's personal knowledge base.","Use the remember tools to capture decisions, meetings, ideas, learnings, and references.","Use the log tool to add entries to the daily note.","Use the connect tools to build links between related notes.","Always check the vault before asking the user to repeat information they may have already documented.","When creating notes, use appropriate templates and add relevant tags."].join(" ")}),c=new M(s);return k("Registering tools..."),et(n,c),nt(n,c,s),rt(n,c,s),st(n,c,s),it(n,c),at(n,c),ct(n,c),lt(n,c),dt(n,c),k("Registering resources..."),ft(n,c,s),k("Server configured with 40 tools and 4 resources"),n}var Y={vault:"",dailyNotes:{folder:"Daily",format:"YYYY-MM-DD"},templates:{folder:"Templates/MindCache"},inbox:{folder:"MindCache/Inbox",requireReview:false}};function Ot(s){let n={},c="";for(let t of s.split(`
 `)){let e=t.replace(/#.*$/,"").trimEnd();if(!e.trim())continue;let o=e.length-e.trimStart().length,r=e.trim(),i=r.indexOf(":");if(i<0)continue;let a=r.slice(0,i).trim(),d=r.slice(i+1).trim();o===0&&!d?(c=a,n[c]||(n[c]={})):o>0&&c?n[c][a]=d:n[a]=d;}return n}function _t(){let s=[resolve(process.cwd(),".mindcache.yml"),resolve(process.cwd(),".mindcache.yaml"),join(homedir(),".config","mindcache","config.yml"),join(homedir(),".config","mindcache","config.yaml"),join(homedir(),".mindcache.yml")];for(let n of s)if(existsSync(n))return n;return null}function j(){let s={vault:Y.vault,dailyNotes:{...Y.dailyNotes},templates:{...Y.templates},inbox:{...Y.inbox}};process.env.MINDCACHE_VAULT&&(s.vault=process.env.MINDCACHE_VAULT);let n=process.env.MINDCACHE_CONFIG||_t();if(n&&existsSync(n)){k(`Loading config from ${n}`);try{let c=readFileSync(n,"utf-8"),t=Ot(c);typeof t.vault=="string"&&(s.vault=t.vault);let e=t.daily_notes??t.dailyNotes;e&&(e.folder&&(s.dailyNotes.folder=e.folder),e.format&&(s.dailyNotes.format=e.format));let o=t.templates;o&&o.folder&&(s.templates.folder=o.folder);let r=t.inbox;r&&(r.folder&&(s.inbox.folder=r.folder),r.require_review&&(s.inbox.requireReview=r.require_review==="true"));}catch(c){ut(`Failed to parse config: ${c instanceof Error?c.message:String(c)}`);}}return s.vault.startsWith("~")&&(s.vault=s.vault.replace("~",homedir())),s}var Ht=`
 MindCache v${F} \u2014 Your Obsidian vault, connected to AI.