Claude Memory MCP

A persistent memory system for Claude Code CLI that stores memories in an Obsidian-compatible markdown vault.

Disclaimer

THIS 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.

Use at your own risk. The authors are not responsible for any data loss, corruption, or other issues that may arise from using this software.

Installation

npx claude-memory-mcp init

Usage

Initialize a vault in your project

npx claude-memory-mcp init

This creates:

• .claude-memory/ - The vault directory
• .mcp.json - MCP server configuration
• CLAUDE.md - Instructions for Claude

Bootstrap with initial context

npx claude-memory-mcp bootstrap

Interactive prompts to populate your vault with project info, tech stack, and decisions.

Check vault health

npx claude-memory-mcp doctor

MCP Server Configuration

The init command automatically creates the correct .mcp.json for your platform.

Windows (requires cmd wrapper):

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "claude-memory-mcp", "serve", "--vault", ".claude-memory"]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "claude-memory-mcp", "serve", "--vault", ".claude-memory"]
    }
  }
}

Features

• 21 MCP tools for Claude to read/write memories
• Obsidian-compatible markdown with YAML front matter
• 8 memory types: decision, pattern, standard, concept, error, troubleshooting, question, session
• Automatic context loading at session start
• Wikilinks for cross-referencing memories
• Supersession tracking for architectural decisions

Memory Types

| Type | Purpose | |------|---------| | decision | Architectural Decision Records (ADRs) | | pattern | Reusable code patterns | | standard | Coding standards and conventions | | concept | Domain concepts and explanations | | error | Error solutions and fixes | | troubleshooting | Debugging guides | | question | Open questions to investigate | | session | Session summaries |

Viewing in Obsidian

The .claude-memory vault is fully compatible with Obsidian:

1. Open Obsidian
2. Click "Open folder as vault"
3. Select the .claude-memory folder in your project
4. Enable "Properties view" in Settings > Editor to see YAML front matter as a table

The vault structure:

.claude-memory/
├── memories/
│   ├── decisions/
│   ├── patterns/
│   ├── standards/
│   ├── concepts/
│   ├── errors/
│   ├── troubleshootings/
│   ├── questions/
│   └── sessions/
├── _templates/
└── _archive/

Example Prompts

Test the memory system with these prompts in Claude Code:

Saving memories:

• "Save a decision: We're using PostgreSQL for the database because of ACID compliance"
• "Save a pattern for retry logic with exponential backoff"
• "Save a coding standard: All functions must have JSDoc comments"
• "I just fixed a bug where JSON.parse failed on undefined input - save this error"

Retrieving memories:

• "What decisions have we made?"
• "Show me all saved patterns"
• "Search memories for 'database'"
• "What's the context for this project?"

Session management:

• "Start a new session"
• "End session with summary: implemented user authentication"

Maintenance:

• "Show vault status"
• "Archive the old session memories"

Troubleshooting

MCP server not connecting

1. Verify .mcp.json exists in your project root
2. Check the configuration:

   {
     "mcpServers": {
       "memory": {
         "command": "npx",
         "args": ["-y", "claude-memory-mcp", "serve", "--vault", ".claude-memory"]
       }
     }
   }

3. Restart Claude Code after changes to .mcp.json

"Vault not found" error

Run npx claude-memory-mcp init in your project directory to create the vault.

Memories not showing in Obsidian

• Make sure you opened the .claude-memory folder directly as a vault
• Check that files exist in .claude-memory/memories/ subdirectories
• Refresh the file explorer in Obsidian (click away and back)

Bootstrap fails with "Invalid tech tag format"

Tech tags must be lowercase alphanumeric with hyphens only. Use:

• react, typescript, postgresql (comma-separated)
• dotnet-core (hyphens, not spaces)

Doctor shows validation errors

Run npx claude-memory-mcp doctor to see specific issues. Common fixes:

• Missing required fields: Edit the memory file to add summary, type, or id
• Invalid enum values: Check that type, status, confidence use valid values

Permission errors on Windows

Run your terminal as Administrator, or check that the project folder isn't read-only.

License

MIT License - See LICENSE for details.