sandraschi/advanced-memory-mcp

Advanced Memory MCP

A Model Context Protocol server that integrates personal knowledge management with Claude Desktop. Features include knowledge graphs, zettelkasten note-taking, and experimental Claude Skills integration.

New in v1.0.0b3: Experimental Claude Skills export and unified database architecture.

Quick Start | | |

✨ Tool Modes

PORTMANTEAU MODE (Default): 15 clean, organized tools - Perfect for Claude Desktop FULL MODE (Opt-in): 56 individual tools - For testing/development only

Result: No tool explosion! Clean, usable interface.

See for details.

Features

1. Claude Skills Format Conversion (Experimental)

# Export zettelkasten → Claude Skills format
adn_export("claude_skills", export_path="~/claude-skills/")

# Import Claude Skills → Advanced Memory notes
adn_import("claude_skills", source_path="~/anthropic-skills/")

Bidirectional format conversion between zettelkasten notes and Anthropic's Claude Skills format. Conversion tools are functional. Deployment to Claude interfaces varies (claude.ai/API verified, Claude Desktop pending verification). Part of the emerging Claude Skills ecosystem with growing community repositories.

2. Reference Library (Experimental)

87+ curated reference templates across 12 categories for systematic learning:

• Developer: Python, Git, Docker, CI/CD, Clean Code (30+ templates)
• DevOps: Kubernetes, Infrastructure as Code, Observability (15+ templates)
• Data Scientist: ML, MLOps, Python for Data Science (10+ templates)
• Researcher: Research Methods, Literature Review, Critical Thinking (12+ templates)
• Product Manager: Strategy, Analytics, Metrics (8+ templates)
• Plus: Entrepreneur, Creative, Writer, UX Designer, Knowledge Worker, AI, Philosophy

Note: These are comprehensive reference documents (1000-5000 words), not classic atomic zettelkasten notes. See for the distinction. Classic zettelkasten support (atomic notes) planned for v1.1.

3. Cursor IDE Compatible - Tool Mode Selection

Problem: Most MCPs have 40+ tools → breaks Cursor's 50-tool limit Solution: Choose between 11 portmanteau tools or full 50+ tools

Portmanteau Mode (11 tools - Cursor compatible)

adn_content    → write, read, view, view_rendered, edit, move, delete
adn_project    → create, switch, list, status, sync
adn_export     → pandoc, docsify, html, pdf, skills!
adn_import     → obsidian, notion, joplin, skills!
adn_search     → search everywhere
adn_knowledge  → analytics, research, bulk ops
adn_navigation → explore, recent, context
adn_editor     → notepad++, typora integration
adn_zettelmaker→ generate, expand, suggest
adn_inbox      → file drop processing
help           → documentation

Enable portmanteau-only mode (for Cursor IDE):

{
  "mcpServers": {
    "advanced-memory": {
      "env": {
        "ADVANCED_MEMORY_PORTMANTEAU_ONLY": "true"
      }
    }
  }
}

11 tools total = fully compatible with Cursor IDE Zero functionality loss - all features available through portmanteau tools

See for details.

4. Unified Database Architecture

• Single global database (~/.advanced-memory/memory.db)
• Project isolation via project_id
• Fast sync (2000+ notes in seconds)
• Configurable file indexing (all files or .md only)

Quick Start

Installation

Step 1: Install the package

pip install advanced-memory-mcp

Step 2: Configure your MCP client

Cursor IDE or VS Code (One-Click)

# Generate deeplink for Cursor
advanced-memory deeplink cursor

# Generate configuration for VS Code
advanced-memory deeplink vscode

# Interactive setup wizard
advanced-memory setup

Claude Desktop

Option 1: MCPB Package (Recommended for Claude Desktop)

1. Download advanced-memory-mcp.mcpb from Releases
2. Open Claude Desktop → Settings → Extensions
3. Drop the .mcpb file
4. Configure project path in Extensions UI

Option 2: Manual Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "advanced-memory": {
      "command": "python",
      "args": ["-m", "advanced_memory.mcp.server"]
    }
  }
}

Or generate the configuration:

advanced-memory deeplink claude-desktop

Option 3: Windows Bootstrap (No MCPB)

Use this when you cannot install the .mcpb package (e.g., Windsurf/Cursor on Windows).

Prerequisites: Node.js 18+, Git for Windows, Python 3.11+, uv.

# Clones to D:\Dev\repos\advanced-memory-mcp by default
npx --yes github:sandraschi/advanced-memory-mcp/scripts/bootstrap/windows

# Custom target location
npx --yes github:sandraschi/advanced-memory-mcp/scripts/bootstrap/windows -- --target C:\Work\mcp

# Also emit Cursor/Windsurf/Claude config templates
npx --yes github:sandraschi/advanced-memory-mcp/scripts/bootstrap/windows -- --generate-configs

What it does:

• Verifies dependencies (Git, Python, uv)
• Clones or updates advanced-memory-mcp
• Runs uv sync, uv run ruff check ., and a skills validation smoke test
• Optionally writes ready-to-use config templates into bootstrap-configs/

An npm-published bootstrapper will follow; the script above is ready for npm publish when we are.

📖 Complete Installation Guide: |

First Steps

You: "Create a new project for my research notes"
Claude: Created project "research-notes"

You: "Generate starter zettelkasten for developer topics" (experimental)
Claude: Created 30+ interconnected notes on Python, Git, Docker, etc.

You: "Export my notes as Claude Skills" (experimental)
Claude: Exported 30 skills to ~/claude-skills/

Testing & Diagnostics

• pwsh ./scripts/testing/run-all-tool-exercisers.ps1 Runs the four portmanteau exerciser suites (core tools, import/export, skills, health/status) and stops at the first failure.
• Flags: -SkipHeavy (skip archive export/import), -SkipNetwork (skip Wikipedia/arXiv calls), -SkipPackaging (skip skills ZIP packaging). Combine flags as needed.
• Individual Python scripts live in scripts/testing/ if you need to probe a single tool group.

Core Capabilities

Claude Skills Format Conversion (Experimental)

Export to Skills format:

adn_export("claude_skills", export_path="~/claude-skills/")
# Creates proper SKILL.md files for claude.ai, API, or community sharing

Import from Skills format:

adn_import("claude_skills", source_path="~/anthropic-skills/",
           destination_folder="skills/anthropic")
# Imports community skills into your knowledge base

Status: Format conversion fully functional. Deploy to claude.ai (paid), Claude API, or share via GitHub. Claude Desktop integration pending verification.

Resources:

• - How to use
• - Complete ecosystem tracking
• Anthropic Skills Repo - Official examples
• Skills Spec - Format specification
• Claude Skills Docs - Official support

Intelligent File Sync

Index everything or markdown only:

{
  "index_all_files": true  // Code repos: true, Pure notes: false
}

Archive old content without deletion:

• Folders with -backup-, .obsolete, -archived automatically skipped
• Preserves files but excludes from indexing
• Perfect for keeping history without clutter

Multi-Format Export

All exports work out of the box! ✨ No paths needed!

adn_export("pdf")                    # → Desktop/advanced-memory-exports/pdf/
adn_export("pandoc", format_type="docx")  # → Desktop/advanced-memory-exports/pandoc/
adn_export("docsify")                # → Desktop/advanced-memory-exports/docsify/
adn_export("claude_skills")          # → Desktop/advanced-memory-exports/claude_skills/
adn_export("html")                   # → Desktop/advanced-memory-exports/html/

Smart defaults: Exports go to your Desktop (or specify custom path) Zero setup: Everything auto-installs on first use PDF: Pure Python (weasyprint) - no LaTeX needed! ⚡ DOCX/EPUB: Pandoc auto-downloads (~100MB, one-time)

Documentation:

Import from Anywhere

Prerequisites: Requires existing exports/vaults from respective applications.

adn_import("obsidian", source_path="~/obsidian-vault/")  # Requires: Obsidian vault
adn_import("notion", source_path="notion-export.zip")    # Requires: Notion export
adn_import("joplin", source_path="~/joplin-export/")     # Requires: Joplin export
adn_import("evernote", source_path="export.enex")        # Requires: Evernote ENEX file
adn_import("claude_skills", source_path="~/skills/")     # Requires: Skills repository

External Tools:

• Obsidian - Local-first note-taking
• Notion - Collaborative workspace
• Joplin - Open-source notes
• Evernote - Note organization

Documentation:

📖 Documentation

Getting Started

• - Step-by-step setup
• - Get productive in 5 minutes
• - Common issues

Core Features

• - Bidirectional conversion (experimental, )
• - 87+ learning templates (experimental, )
• - Cursor IDE compatibility (10 tools)
• - Unified global database

Technical & Development

• - Architecture, dependencies, build system, CI/CD
• - Extend and customize
• - System design
• - Feature verification status

Use Cases

For Development Teams

Centralize team knowledge in a structured format:

# Document team standards in Advanced Memory
# Export as Claude Skills (experimental)
adn_export("claude_skills", export_path="~/team-skills/", source_folder="team/standards")

For Researchers

Research-focused templates include:

• Research Methods Overview
• Systematic Literature Review
• Critical Thinking
• Data Analysis Fundamentals
• Academic Writing

Templates are experimental and coverage varies by domain.

For Solo Developers

Integration options for Cursor IDE:

1. Index your codebase (all files)
2. Generate developer zettelkasten templates (experimental)
3. Export as Skills for Claude (experimental)

Provides context-aware AI assistance with your knowledge base.

🏗️ Architecture Highlights

Unified Database (v1.0.0b3)

• Single global database: ~/.advanced-memory/memory.db
• Project isolation: via project_id (not separate databases)
• Fast sync: 2000+ notes indexed in seconds
• Portable: Export/import entire system as archive

Portmanteau Tools

40+ individual tools consolidated into 10 comprehensive tools:

Result: Full functionality in 10 tools (Cursor IDE: ✅ Compatible!)

What's New in v1.0.0b3

Claude Skills Format Conversion (Experimental)

• Export: zettelkasten → Claude Skills format (SKILL.md)
• Import: Claude Skills → Advanced Memory notes
• Bidirectional metadata preservation
• Compatible with claude.ai, Claude API, emerging community ecosystem
• Claude Desktop deployment pending verification

Database Architecture Fixes

• Fixed ADVANCED_MEMORY_HOME defaulting to ~/.advanced-memory/
• Unified global database (removed per-project databases)
• Fixed MCPB config path issues
• Project isolation via project_id

File Sync Improvements

• index_all_files config option (index all files or .md only)
• ARCHIVE_PATTERNS (skip backup/obsolete folders)
• Enhanced diagnostic logging

MCPB Portmanteau-Only

• MCPB exposes 10 portmanteau tools (not 50+ individual tools)
• Cursor IDE compatibility
• Full functionality via consolidated tools

Python Compatibility

• Python 3.11, 3.12, 3.13 tested
• Python 3.10 compatible
• All 1113 tests passing

Learning Resources

Zettelkasten Templates (Experimental)

87+ templates across 12 categories:

Developer (30+ templates):

• Python: Fundamentals, Type Hints, Async, Testing
• Git: Version Control, Workflows
• Docker: Containers, Compose
• CI/CD: GitHub Actions, Pipelines
• Clean Code: Principles, Patterns, OOP
• System Design: Microservices, Event-Driven, Distributed Systems

Data Scientist (10+ templates):

• Machine Learning Fundamentals
• Python for Data Science
• ML Model Deployment

Researcher (12+ templates):

• Research Methods Overview
• Systematic Literature Review
• Critical Thinking
• Academic Writing

Additional categories: DevOps, Product Manager, Entrepreneur, Creative, Writer, UX Designer, Knowledge Worker, AI, Philosophy

Template quality and coverage vary. Consider them starting points for customization.

Documentation

• - Everything you need
• - Skills export/import
• - Common issues
• - Extend and customize

🛠️ Technical Details

Built With

• MCP Protocol: Model Context Protocol for LLM integration
• FastMCP: High-performance MCP server framework
• SQLAlchemy: Robust database ORM with async support
• Pydantic: Type-safe configuration and validation
• Whoosh: Full-text search indexing
• Python-Frontmatter: YAML frontmatter parsing

Requirements

• Python 3.11+ (3.10 compatible, 3.13 tested)
• Claude Desktop or any MCP-compatible client
• Windows, macOS, or Linux

Compatibility

• ✅ Claude Desktop: Native MCP integration
• ✅ Cursor IDE: 10 portmanteau tools (fully compatible)
• ✅ Claude Skills: Bidirectional export/import
• ✅ Obsidian: Import vaults, export to Obsidian format
• ✅ Notion: Import/export workspaces
• ✅ Joplin: Import/export knowledge bases
• ✅ Evernote: Import ENEX files

Example Workflows

Workflow 1: Team Knowledge to Claude Skills (Experimental)

# 1. Document team standards in Advanced Memory
adn_content("write", identifier="Python Standards",
            content="# Our Python Standards\n\n...", folder="team/standards")

# 2. Export as Claude Skills (experimental)
adn_export("claude_skills", export_path="~/team-skills/", source_folder="team")

# 3. Configure Claude Desktop: Settings → Skills → Add Directory → ~/team-skills/

Workflow 2: Import and Enhance Skills (Experimental)

# 1. Import Anthropic's official skills
adn_import("claude_skills", source_path="~/anthropic-skills/mcp-builder/",
           destination_folder="skills/mcp")

# 2. Enhance with your own notes and links

# 3. Export enhanced version
adn_export("claude_skills", export_path="~/enhanced-mcp-skills/",
           source_folder="skills/mcp")

Workflow 3: Zettelkasten Generation (Experimental)

# 1. Generate starter templates
adn_zettelmaker("generate", category="data-scientist", topic="machine-learning")

# 2. Customize and enhance notes

# 3. Export as Skills (experimental)
adn_export("claude_skills", export_path="~/ml-skills/",
           source_folder="data-scientist")

🚀 Installation Options

For Cursor IDE and VS Code

One-click installation via deeplinks provides the fastest setup:

pip install advanced-memory-mcp
advanced-memory deeplink cursor  # or 'vscode'

Deeplinks automatically configure the MCP connection in your IDE.

For Claude Desktop

MCPB Package (Recommended):

• Download .mcpb from Releases
• Drag into Claude Desktop Settings → Extensions
• Configure via GUI

Manual Configuration:

• Install via pip install advanced-memory-mcp
• Add configuration to claude_desktop_config.json
• See for details

For Other MCP Clients

Install the Python package and configure manually per your client's documentation:

pip install advanced-memory-mcp
advanced-memory mcp  # Verify installation

📊 Project Stats

• 1113 tests passing (100% pass rate)
• 87+ reference templates (12 categories, experimental - comprehensive guides, not atomic zettelkasten)
• 10 portmanteau tools (Cursor IDE compatible)
• 54% test coverage (growing)
• Python 3.11-3.13 supported (3.10 compatible)
• Zero ruff errors (strict linting)

⚠️ Testing Status

Public Repo Notice: We're committed to transparency about feature verification.

Verified ✅:

• Core content management (write, read, edit, delete)
• Project management (create, switch, list)
• Claude Skills export/import (format conversion)
• Database architecture (global db with project isolation)

Pending Real-World Verification ⏳:

• Import/export features (Obsidian, Notion, Joplin, Evernote)
• Reference template quality and coverage
• Editor integrations (Notepad++, Typora)

Auto-Installed ✅:

• Pandoc: Downloads automatically on first export (~100MB, one-time)
• Mermaid.js: Loaded from CDN for diagram rendering
• weasyprint: Pure-Python PDF generation (no LaTeX needed!)

Optional Dependencies 🔧:

• wkhtmltopdf: Alternative PDF engine (if weasyprint has issues)
  • Windows: winget install wkhtmltopdf
  • macOS: brew install wkhtmltopdf
  • Linux: sudo apt install wkhtmltopdf
• LaTeX (MiKTeX/TinyTeX): For advanced PDF typography

External Tools (optional for specific imports) 🔧:

• Obsidian/Notion/Joplin/Evernote: Only needed if importing FROM those platforms (we just read their export files)

Everything else: ✅ Works immediately after pip install!

• See for details

We're actively testing and will update status as features are verified.

🤝 Contributing

We welcome contributions! See:

• - How to contribute
• - Development setup
• - Community standards

Quick Contribution Ideas

• 🎨 Create new zettelkasten templates for your domain
• 📝 Improve documentation
• 🐛 Report bugs or suggest features
• 🌐 Translate documentation
• 🔧 Add new export/import formats

📜 License

AGPL-3.0-or-later - Free and open source

This ensures:

• ✅ You can use it freely (personal or commercial)
• ✅ You can modify and extend it
• ✅ You must share improvements (keeps it open source)

🙏 Credits

Built with inspiration from:

• Anthropic Claude Skills - Agent skills framework
• Zettelkasten Method - Knowledge management methodology
• Model Context Protocol - LLM integration standard
• FastMCP - High-performance MCP framework

🔗 Links

• Documentation:
• Releases: GitHub Releases
• Issues: Bug Reports & Features
• Claude Skills:

Quick Command Reference

# Content Management
adn_content("write", identifier="Title", content="...", folder="notes")
adn_content("read", identifier="Title")
adn_content("edit", identifier="Title", operation="append", content="...")

# Project Management
adn_project("create", project_name="research", project_path="~/Documents/research")
adn_project("switch", project_name="research")
adn_project("list")

# Claude Skills (Experimental)
adn_export("claude_skills", export_path="~/claude-skills/")
adn_import("claude_skills", source_path="~/anthropic-skills/")

# Zettelkasten Generation (Experimental)
adn_zettelmaker("generate", category="developer", topic="python-core")

# Search
adn_search("notes", query="async programming")

# Export
adn_export("pandoc", export_path="output.pdf", format_type="pdf")
adn_export("docsify", export_path="docs/")

Why Advanced Memory?

Key characteristics:

• Open source (AGPL-3.0)
• Local-first (files on your computer, works offline)
• MCP integration (designed for Claude Desktop)
• Cursor IDE compatible (via portmanteau tools)
• Extensible (import/export from multiple sources)

Experimental features:

• Claude Skills export/import
• Reference template library (comprehensive learning guides)
• Classic zettelkasten (atomic notes) planned for v1.1

_{Local-first knowledge management with MCP integration}

• • • Report Bug