@mandays/obsidian-memory-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# obsidian-memory-mcp
+
+MCP (Model Context Protocol) server for **Obsidian v3 Atomic Markdown Memory** vaults.
+
+Provides standardized tools for any AI assistant (Claude Code, Claude Desktop, ChatGPT, Codex, Qoder, Open Code, Hermes Agent, Antigravity, Open Claw) to read, write, search, and manage Obsidian vault memory using the [v3 Atomic Markdown Memory](https://github.com/jrcruciani/obsidian-memory-for-ai) specification.
+
+## Installation
+
+```bash
+npm install -g obsidian-memory-mcp
+# or run directly
+npx obsidian-memory-mcp --vault ~/path/to/vault
+```
+
+## Quick Start
+
+### stdio mode (Claude Code, Qoder, Open Code)
+
+```bash
+npx obsidian-memory-mcp --vault ~/obsidian-vault
+```
+
+### SSE/HTTP mode (Desktop apps)
+
+```bash
+npx obsidian-memory-mcp --vault ~/obsidian-vault --transport sse --port 3100
+```
+
+### Initialize a new vault
+
+```bash
+npx obsidian-memory-mcp --vault ~/new-vault
+# Then call the vault_init tool
+```
+
+## MCP Client Configuration
+
+### Claude Code / Qoder
+
+Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "obsidian-memory": {
+      "command": "npx",
+      "args": ["obsidian-memory-mcp", "--vault", "/path/to/vault"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "obsidian-memory": {
+      "command": "npx",
+      "args": ["obsidian-memory-mcp", "--vault", "/path/to/vault"]
+    }
+  }
+}
+```
+
+### Multi-agent (inbox mode)
+
+```json
+{
+  "mcpServers": {
+    "obsidian-memory": {
+      "command": "npx",
+      "args": [
+        "obsidian-memory-mcp",
+        "--vault", "/path/to/vault",
+        "--mode", "inbox",
+        "--agent-id", "agent-claude-1a2b3c4d"
+      ]
+    }
+  }
+}
+```
+
+## Available Tools (20)
+
+### Read/Query
+
+| Tool | Description |
+|------|-------------|
+| `read_fact` | Read a fact by entity+predicate or ID |
+| `read_entity` | Get all facts for an entity |
+| `read_event` | Find events by date range, entity, or kind |
+| `search_memory` | Flexible search with text, entity, predicate, date, confidence, tags |
+| `get_view` | Read materialized views (timeline, contradictions, stale, graph, etc.) |
+
+### Write
+
+| Tool | Description |
+|------|-------------|
+| `create_fact` | Create a new atomic fact |
+| `update_fact` | Update an existing fact (with precondition hash) |
+| `add_event` | Record an append-only event |
+| `archive_fact` | Archive a fact to `_archive/` |
+
+### Maintenance
+
+| Tool | Description |
+|------|-------------|
+| `lint_vault` | Full schema validation |
+| `rebuild_views` | Regenerate all `_views/` files |
+| `compact_inbox` | Apply proposed operations from inbox |
+| `reflect` | Create a reflection/observation event |
+
+### Schema Management
+
+| Tool | Description |
+|------|-------------|
+| `list_entities` | List registered entities |
+| `list_predicates` | List allowed predicates |
+| `add_entity` | Register a new entity |
+| `add_predicate` | Register a new predicate |
+| `get_schema` | Get YAML schema for a type |
+
+### Vault
+
+| Tool | Description |
+|------|-------------|
+| `vault_init` | Scaffold a new v3 vault |
+| `vault_status` | Health overview with counts |
+
+## CLI Options
+
+```
+--vault <path>        Path to vault root (required, or set VAULT_PATH env)
+--transport <type>    stdio (default) or sse
+--agent-id <id>       Agent identity for this instance
+--mode <mode>         direct (default) or inbox
+--port <port>         SSE port (default: 3100)
+--api-key <key>       API key for SSE auth
+--stale-days <days>   Days before a fact is stale (default: 180)
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `VAULT_PATH` | Path to vault (alternative to `--vault`) |
+| `TRANSPORT` | Transport type |
+| `AGENT_ID` | Agent identity |
+| `WRITE_MODE` | direct or inbox |
+| `PORT` | SSE port |
+| `API_KEY` | SSE authentication key |
+| `STALE_DAYS` | Stale threshold |
+| `MEMORY_TODAY` | Override "today" for deterministic views |
+
+## Write Modes
+
+### Direct (default)
+
+Single-agent mode. Writes go directly to vault files. Safe for single AI tool usage.
+
+### Inbox
+
+Multi-agent mode. Writes create operation envelopes in `memory/_inbox/{agent-id}/ops/`. Use `compact_inbox` to validate and apply them. Supports precondition hashes and advisory claims for conflict detection.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development
+npm run dev -- --vault ./test/fixtures/v3-vault
+
+# Run tests
+npm test
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+```
+
+## Architecture
+
+The server ports the complete v3 toolchain (lint.py, compact.py, rebuild_views.py, ops.py, query.sh) to TypeScript, providing a self-contained npm package with no Python dependency.
+
+```
+MCP Tool Layer
+     │
+     ▼
+Query Engine │ Operation Manager │ View Generator │ Schema Validator
+     │                │                  │                │
+     ▼                ▼                  ▼                ▼
+Vault Service (path resolution, entity/predicate registries)
+     │
+     ▼
+Markdown Service (frontmatter parse/serialize via gray-matter)
+```
+
+## License
+
+MIT