obsidian-hippocampus-mcp

We gave Obsidian a hippocampus. Now it remembers what matters, forgets what doesn't, and works with your AI as a single cognitive system.

What we built and why it matters

Obsidian is the best second brain ever made. 4 million people use it. But there's a problem: it's passive. You write. You organize. You search. The intelligence is 100% on your side.

We built hippocampus-mcp to fix that.

hippocampus-mcp is an MCP server that connects your Obsidian vault directly to any AI agent (Claude, Cursor, Windsurf, any MCP client). It gives Obsidian something it never had: a working memory system. Not just storage — memory. With recall, forgetting, semantic search, and bidirectional sync.

Here's what happens when you connect them:

Before hippocampus-mcp

Obsidian → Your notes sit there until you read them
Your AI  → Starts from zero every conversation
You      → Copy-paste between your brain and your AI

After hippocampus-mcp

Your AI learns something new
  ↓
It writes to your Obsidian vault (hippocampus-memories/)
  ↓
You open Obsidian: the AI's memory is RIGHT THERE as a markdown note
  ↓
You edit it, tag it, link it to other notes
  ↓
Your AI reads your changes, adjusts its understanding
  ↓
Both of you share ONE knowledge base — your vault

This isn't a plugin. It's a cognitive bridge. Obsidian becomes the shared memory layer between you and every AI you use.

What makes this different from every other memory system

| System | Storage | You can see it? | You can edit it? | Survives AI shutdown? | |--------|---------|-----------------|-------------------|----------------------| | MemPalace | Proprietary DB | ❌ | ❌ | ✅ | | supermemory | Cloud DB | ❌ | ❌ | ✅ | | mem0 | Vector DB | ❌ | ❌ | ✅ | | Claude Projects | Claude's servers | Partial | ❌ | ✅ | | hippocampus-mcp | Your Obsidian vault | ✅ Markdown files | ✅ Any editor | ✅ Your data, your rules |

Every AI memory system treats your AI's memories as proprietary data in a black box. Only hippocampus-mcp puts them in your Obsidian vault — plain markdown files you own, edit, tag, graph, publish, and back up.

What Obsidian can do now that it couldn't before

1. Remember conversations

Obsidian stores what you write. Now it also stores what your AI learns. Every remember() call creates a markdown file in hippocampus-memories/. Your AI's experiences become part of your knowledge base.

2. Recall semantically (not just keyword search)

Obsidian's built-in search is string-based. hippocampus-mcp adds TF-IDF 128-dimensional embeddings with cosine similarity search. Query "how should I handle user auth?" and it finds the memory about JWT best practices even if the word "auth" never appears in the query.

3. Forget naturally (like a real brain)

Not all memories are worth keeping. hippocampus-mcp implements the Ebbinghaus forgetting curve (R = e^(-t/s)). Memories you never access decay. Weak memories get pruned. Your vault doesn't bloat with irrelevant context. The forgetting is tunable — tag something important or permanent and it resists decay.

4. Sync bidirectionally

Write a note in Obsidian → your AI reads it. Your AI stores a memory → you see it as a markdown file. Edit the AI's memory → the AI adjusts its recall. This bidirectional loop means your knowledge base and your AI's knowledge base are the same thing.

5. Multi-agent memory

Use Claude Desktop at work, Cursor for coding, Windsurf for design. With hippocampus-mcp, all of them share the same memory — your Obsidian vault. One agent's learning is another agent's context.

How it works (technical but you'll get it)

┌─────────────────────────────────────────────────────────┐
│                   YOUR OBSIDIAN VAULT                   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  hippocampus-memories/                           │   │
│  │  ├── user-preference.md                          │   │
│  │  ├── project-decision.md                         │   │
│  │  ├── audit-result.md                             │   │
│  │  └── ... markdown files, one per memory          │   │
│  └──────────────────────────────────────────────────┘   │
│                         ↕                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │  HIPPOCAMPUS-MCP MEMORY ENGINE                   │   │
│  │                                                  │   │
│  │  • Ebbinghaus forgetting curve                   │   │
│  │    Score(t) = S₀ × e^(-t/τ)                      │   │
│  │    Unused memories decay. Recalled ones boost.   │   │
│  │                                                  │   │
│  │  • TF-IDF semantic embeddings (128 dimensions)   │   │
│  │    Deterministic — no API call, no cloud cost.   │   │
│  │    Pure math: TF × IDF × cosine similarity       │   │
│  │                                                  │   │
│  │  • Multi-factor ranking                          │   │
│  │    Score = 0.3(semantic) + 0.4(recency)          │   │
│  │          + 0.2(frequency) + 0.1(emotional)       │   │
│  │    × 1.5 if tagged important/permanent           │   │
│  └──────────────────────────────────────────────────┘   │
│                         ↕                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │  MCP SERVER (Model Context Protocol)             │   │
│  │  Port 3099 · JSON-RPC 2.0 · 5 tools              │   │
│  │                                                  │   │
│  │  remember()  → write markdown to vault           │   │
│  │  recall()    → semantic search with scoring      │   │
│  │  forget()    → Ebbinghaus decay + prune          │   │
│  │  obsidian_sync() → bidirectional import/export   │   │
│  │  status()    → engine health + stats             │   │
│  └──────────────────────────────────────────────────┘   │
│                         ↕                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │  YOUR AI (Claude, Cursor, Windsurf, any MCP)     │   │
│  │  "Remember that the user prefers TypeScript"     │   │
│  │  → creates hippocampus-memories/user-preference… │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Every memory is a markdown file. Every markdown file in your vault is a potential memory. The boundary between "your notes" and "your AI's notes" disappears.

Quick Start

# Install globally
npm install -g agic-hippocampus-mcp

# Auto-detect your Obsidian vault and start
hippocampus-mcp start

# Or point to a specific vault
hippocampus-mcp start --vault "/path/to/your/vault"

# See detected vaults
hippocampus-mcp detect

# Check memory stats
hippocampus-mcp status

Then configure any MCP client:

{
  "mcpServers": {
    "hippocampus": {
      "command": "hippocampus-mcp",
      "args": ["start"]
    }
  }
}

MCP Tools

| Tool | What it does | When to use it | |------|-------------|----------------| | remember | Stores an AI experience as a markdown file in your vault | "I learned something I should never forget" | | recall | Semantic search across all memories | "What do I know about X?" | | forget | Run Ebbinghaus decay to prune weak memories | "Clean up irrelevant context" | | obsidian_sync | Import vault notes / export memories | "Sync my latest thinking into AI memory" | | status | Engine health, memory count, top tags | "How's my AI's memory doing?" |

Example: how an AI uses it

User: "I prefer TypeScript over JavaScript. Use tabs, not spaces."

AI: [internally calls remember("user-preference-editor", "User prefers TypeScript, tabs over spaces")]
     → Creates hippocampus-memories/user-preference-editor.md in your Obsidian vault

Later:
User: "Write a React component"

AI: [internally calls recall("code preferences")]
     → Finds the memory: "User prefers TypeScript, tabs over spaces"
     → Writes TypeScript code with tab indentation

You: Open Obsidian → see hippocampus-memories/user-preference-editor.md
     Change: "Actually I'm using spaces now"
     → Next AI recall reflects your update

When to use it

• Claude Code — persistent memory across sessions (stop explaining your preferences every time)
• Cursor/Windsurf — AI that remembers your codebase, your stack, your style
• Personal AI — your AI reads your daily notes, you read your AI's analysis
• Second brain 2.0 — Obsidian was your second brain. Now it's your AI's brain too.
• Multi-agent — Claude + Cursor + Windsurf all share the same memory through one vault

When NOT to use it

• You want your AI to have amnesia (some use cases need statelessness)
• You don't use Obsidian (but you should — 4M users can't be wrong)
• You prefer proprietary AI memory vendors (then use MemPalace, mem0, etc.)

CLI

hippocampus-mcp start        # Start MCP server (auto-detect vault)
hippocampus-mcp detect       # Find Obsidian vaults on this machine
hippocampus-mcp status       # Memory engine health
hippocampus-mcp forget       # Run forgetting curve
hippocampus-mcp --help       # All commands

Options:

start:
  -p, --port <number>    Port (default: 3099)
  --vault <path>         Obsidian vault path

forget:
  -t, --threshold <n>    Forget threshold 0-1 (default: 0.1)

MCP Endpoints

POST http://localhost:3099/mcp     # JSON-RPC 2.0
GET  http://localhost:3099/health  # Health check

Quick test

# Store a memory
curl -X POST http://localhost:3099/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"call_tool","params":{"name":"remember","arguments":{"key":"hello-world","content":"hippocampus-mcp stores memories in Obsidian!","tags":["test","important"]}}}'

# Search
curl -X POST http://localhost:3099/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"call_tool","params":{"name":"recall","arguments":{"query":"What do I know about Obsidian?","limit":5}}}'

For MCP-Enabled AI Clients

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "hippocampus": {
      "command": "hippocampus-mcp",
      "args": ["start"]
    }
  }
}

VS Code (Cline, Continue, etc.)

{
  "mcpServers": {
    "hippocampus": {
      "command": "npx",
      "args": ["-y", "hippocampus-mcp", "start"]
    }
  }
}

License

MIT — use it, build on it, share it. Your AI's memory belongs to you.

hippocampus-mcp: we gave Obsidian a memory. Now Obsidian gives your AI one too.