super-memory by Devjoy-digital - MCP Server

Super Memory MCP Server

A Model Context Protocol (MCP) server that allows AI environments like Claude, Gemini, and OpenAI to create and manage memories as Markdown files in your local Obsidian vault.

Created by devjoy.digital ✨

Features

Memory Management: Create, read, update, and delete memory files with structured frontmatter
Obsidian Integration: Stores memories as Markdown files compatible with Obsidian vaults
Directory Navigation: Browse and organize memories within your vault structure
Search Capabilities: Search memories by content, tags, AI model, and date ranges
Configurable: Customizable file naming, default tags, and directory structure
Safe Operations: Path validation prevents directory traversal attacks
Multi-AI Support: Track which AI model created each memory

Installation

Prerequisites

Node.js 18.0.0 or higher
An Obsidian vault (or any directory where you want to store memories)

Local Installation Steps

Get the code:

# Option 1: Clone with git
git clone <repository-url>
cd SuperMemory

# Option 2: Download ZIP and extract, then:
cd SuperMemory

Install and configure:
```
npm install
```
Restart your AI environment (Claude Desktop, VS Code, etc.)

Configure your vault path in your AI environment:

config with vaultPath: "/path/to/your/obsidian/vault"

Universal Installation (Recommended)

The npm install command automatically:

npm install

This single command will:

✅ Install all dependencies
✅ Build the project
✅ Auto-detect your AI environments (Claude Desktop, Cline, etc.)
✅ Configure Super Memory for all detected environments
✅ Create setup files for manual configuration

Targeted Installation

Install for specific AI environments only:

# Install for Claude Desktop only
npm install -- --claude

# Install for Cline (VS Code) only  
npm install -- --cline

# Install for Gemini only
npm install -- --gemini

# Install for multiple specific environments
npm install -- --claude --cline

# Verbose output showing detection process
npm install -- --verbose

# Debug mode with detailed logging
npm install -- --debug

Manual Setup

If you prefer manual configuration:

npm install -- --manual

This creates configuration files without auto-configuring any environments.

Supported AI Environments

✅ Claude Desktop

Automatically detects and configures Claude Desktop on macOS, Windows, and Linux.

✅ Cline (VS Code Extension)

Detects VS Code with Cline extension and creates configuration files.

✅ Google Gemini

Creates setup instructions for when Gemini MCP support becomes available.

✅ ChatGPT

Prepared for future ChatGPT MCP support.

✅ Generic MCP Clients

Universal configuration works with any MCP-compatible AI environment.

Configuration Files

MCP-Config Integration

Super Memory uses the @devjoy-digital/mcp-config package for configuration management:

Local Configuration: config/default.json - Stores non-sensitive configuration values
Environment Variables: .env file for sensitive values (following mcp-config conventions)
Global Configuration: Detects and respects global mcp-config settings
Client Distribution: Automatically distributes configuration to supported clients

Created During Installation

claude_desktop_config.json - Updated with Super Memory server (if Claude detected)
cline_mcp_settings.json - Ready to import into Cline
gemini-setup.md - Setup instructions for Gemini
chatgpt-setup.md - Future setup instructions for ChatGPT
universal-mcp-config.json - Universal configuration for any MCP client
template-config.json - Schema definition for mcp-config

Server Configuration

On first run, use the config tool to set up your Obsidian vault path:

config with vaultPath: "/path/to/your/obsidian/vault"

Available Tools

Configuration Tools

`config`

Configure Super Memory settings including vault path and other options.

Parameters:

vaultPath (string, optional): Absolute path to your Obsidian vault directory
fileExtension (string, optional): File extension for memory files (default: ".md")
fileNameTemplate (string, optional): Template for memory filenames. Variables: {title}, {date}, {timestamp}
defaultTags (array, optional): Default tags to add to all new memories
autoCreateDirectories (boolean, optional): Automatically create directories if they don't exist
defaultSearchLimit (number, optional): Default limit for search results
clients (array, optional): Client applications to distribute configuration to (e.g., ["Claude Desktop", "VS Code"])
allowGlobalOverride (boolean, optional): Allow modification of global configuration (default: false)

`config_get`

Get the current Super Memory configuration.

`get_supported_clients`

Get list of supported client applications for configuration distribution.

Directory Tools

`browse_directories`

Browse directories within your Obsidian vault to navigate and select where to store memories.

Parameters:

path (string, optional): Relative path within vault to browse (use "." for vault root)

`get_current_path_info`

Get detailed information about a specific directory path.

Parameters:

path (string, optional): Relative path within vault to get info about

`create_directory`

Create a new directory within the vault for organizing memories.

Parameters:

path (string, required): Relative path within vault where to create directory
name (string, required): Name of the directory to create

Memory Tools

`create_memory`

Create a new memory file with specified title and content.

Parameters:

title (string, required): Title for the memory (used in filename)
content (string, required): Markdown content of the memory
directoryPath (string, required): Relative path within vault where to save
tags (array, optional): Tags to categorize the memory
aiModel (string, required): AI model creating this memory

`read_memory`

Read the content of an existing memory file.

Parameters:

filePath (string, required): Relative path to the memory file within vault

`update_memory`

Update an existing memory file with new content, title, or tags.

Parameters:

filePath (string, required): Relative path to the memory file within vault
title (string, optional): New title for the memory
content (string, optional): New content for the memory
tags (array, optional): New tags for the memory

`delete_memory`

Delete a memory file from the vault.

Parameters:

filePath (string, required): Relative path to the memory file within vault

`list_memories`

List all memory files in a specific directory.

Parameters:

directoryPath (string, optional): Relative path within vault to list memories from
recursive (boolean, optional): Whether to search subdirectories recursively

Search Tools

`search_memories`

Search for memories by content, tags, or other criteria.

Parameters:

query (string, optional): Text to search for in memory content and titles
tags (array, optional): Tags to filter by
directory (string, optional): Directory to search within
limit (number, optional): Maximum number of results to return
aiModel (string, optional): Filter by AI model that created the memory

`find_memories_by_tag`

Find all memories that have specific tags.

Parameters:

tags (array, required): Tags to search for (memories must have ALL of these tags)
directory (string, optional): Directory to search within
limit (number, optional): Maximum number of results to return

`find_recent_memories`

Find the most recently created or modified memories.

Parameters:

days (number, optional): Number of days to look back (default: 7)
directory (string, optional): Directory to search within
limit (number, optional): Maximum number of results to return (default: 10)
sortBy (string, optional): Sort by "created" or "modified" date

Memory File Format

Memories are stored as Markdown files with YAML frontmatter:

---
created: 2025-01-25T10:23:41.000Z
ai_model: claude-3.5-sonnet
tags: ["example", "documentation"]
title: "Example Memory"
modified: 2025-01-25T11:30:15.000Z
---

# Example Memory

This is the content of the memory. It can contain any Markdown formatting:

- Lists
- **Bold text**
- [Links](https://example.com)
- Code blocks
- Images
- And more!

The frontmatter above contains metadata about when the memory was created,
which AI model created it, tags for organization, and the title.

File Naming

By default, memory files are named using the pattern Memory-{title}.md. You can customize this pattern in the configuration:

{title}: The sanitized memory title
{date}: Current date (YYYY-MM-DD)
{timestamp}: Current timestamp (YYYY-MM-DD-HH-MM-SS)

Examples:

Memory-{title} → Memory-My-Important-Note.md
{date}-{title} → 2025-01-25-My-Important-Note.md
Notes/{title}-{timestamp} → Notes/My-Important-Note-2025-01-25-10-23-41.md

Security

The server includes several security measures:

Path Validation: All file operations are validated to ensure they stay within the configured vault directory
Input Sanitization: Filenames and directory names are sanitized to prevent filesystem issues
Safe File Operations: Uses safe path joining and validation to prevent directory traversal attacks

Development

Project Structure

super-memory/
├── src/
│   ├── models/           # Data models and interfaces
│   │   ├── Memory.ts     # Memory-related interfaces
│   │   └── Config.ts     # Configuration interfaces
│   ├── utils/            # Utility functions
│   │   ├── FileUtils.ts  # File system operations
│   │   ├── PathUtils.ts  # Path validation and sanitization
│   │   └── DateUtils.ts  # Date formatting utilities
│   ├── server/           # Server implementation
│   │   ├── handlers/     # Tool handlers
│   │   │   ├── ConfigHandler.ts     # Configuration management
│   │   │   ├── DirectoryHandler.ts  # Directory operations
│   │   │   ├── MemoryHandler.ts     # Memory CRUD operations
│   │   │   └── SearchHandler.ts     # Search functionality
│   │   └── MemoryServer.ts          # Main server class
│   └── index.ts          # Entry point
├── test/                 # Test files
├── resources/            # Additional resources
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Development Mode

npm run dev

Testing

npm test

Usage Examples

Basic Workflow

Configure the vault path:

config with vaultPath: "/Users/username/Documents/MyVault"

Configure with client distribution:

config with:
- vaultPath: "/Users/username/Documents/MyVault"
- clients: ["Claude Desktop", "VS Code"]

Override global configuration:

config with:
- vaultPath: "/Users/username/Documents/MyVault"
- allowGlobalOverride: true

Browse directories:
```
browse_directories
```

Create a memory:

create_memory with:
- title: "Meeting Notes"
- content: "# Team Meeting\n\nDiscussed project timeline and deliverables..."
- directoryPath: "Work/Meetings"
- tags: ["work", "meeting", "project"]
- aiModel: "claude-3.5-sonnet"

Search for memories:

search_memories with query: "project timeline"

List recent memories:
```
find_recent_memories with days: 7
```

Advanced Usage

Organize by AI model: Create directories for different AI models
Use tags effectively: Tag memories by topic, project, or importance
Search efficiently: Use specific queries and filters to find relevant memories
Regular maintenance: Use the update and delete tools to keep your vault organized

Troubleshooting

Common Issues

"Vault path not configured"
- Use the config tool to set your vault directory
"Path would escape the vault directory"
- Ensure all paths are relative to your vault root
- Don't use ../ or absolute paths in directory parameters
"Directory already exists"
- The directory you're trying to create already exists
- Use browse_directories to see existing directories
"Memory with this title already exists"
- A memory file with the same title already exists in that directory
- Choose a different title or update the existing memory

Debug Information

The server logs debug information to stderr, including:

Server initialization status
Configuration file location
Vault path configuration
Tool registration information

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

Check the troubleshooting section above
Review the tool documentation
Check server logs for error messages
Create an issue with detailed information about your setup and the problem