MemoGraph 🧠

<!-- mcp-name: io.github.Indhar01/memograph -->

A graph-based memory system for LLMs with intelligent retrieval. MemoGraph provides a powerful solution to the LLM memory problem by combining knowledge graphs, hybrid retrieval, and semantic search.

📊 Project Status: MemoGraph is production-ready! See docs/PROJECT_STATUS.md for current status and docs/FUTURE_ENHANCEMENTS.md for optional improvements.

✨ Features

• 🤖 Smart Auto-Organization Engine: Automatically extract structured information from memories using LLMs
• Topics, subtopics, and recurring themes
• People with roles and organizations
• Action items with assignees and deadlines
• Decisions, questions, and sentiment analysis
• Risks, ideas, and timeline events
• 🏷️ AI-Powered Tag Suggestions: Automatically suggest relevant tags using semantic analysis and content structure detection
• 🔗 AI-Powered Link Suggestions: Intelligently recommend wikilinks to related notes using semantic similarity and graph analysis
• Graph-Based Memory: Navigate knowledge using bidirectional wikilinks and backlinks
• Hybrid Retrieval: Combines keyword matching, graph traversal, and optional vector embeddings
• Markdown-Native: Human-readable markdown files with YAML frontmatter
• Memory Types: Support for episodic, semantic, procedural, and fact-based memories
• Smart Indexing: Efficient caching system that only re-indexes changed files
• CLI & Python API: Use via command line or integrate into your Python applications
• Multiple LLM Providers: Works with Ollama, Claude, and OpenAI
• Context Compression: Intelligent token budgeting for optimal context windows
• Salience Scoring: Memory importance ranking for better retrieval

🚀 Quick Start

Installation

pip install memograph

Install with optional dependencies:

# For OpenAI support
pip install memograph[openai]

# For Anthropic Claude support
pip install memograph[anthropic]

# For Ollama support
pip install memograph[ollama]

# For embedding support
pip install memograph[embeddings]

# Install everything
pip install memograph[all]

Python Usage

from memograph import MemoryKernel, MemoryType

# Initialize the kernel attached to your vault path
kernel = MemoryKernel("~/my-vault")

# Ingest all notes in the vault
stats = kernel.ingest()
print(f"Indexed {stats['indexed']} memories.")

# Programmatically add a new memory
kernel.remember(
    title="Meeting Note",
    content="Decided to use BFS graph traversal for retrieval.",
    memory_type=MemoryType.EPISODIC,
    tags=["design", "retrieval"]
)

# Retrieve context for an LLM query
context = kernel.context_window(
    query="how does retrieval work?",
    tags=["retrieval"],
    depth=2,
    top_k=8
)

print(context)

🔌 MCP Server (Model Context Protocol)

MemoGraph includes a full-featured MCP server for seamless integration with AI assistants like Cline and Claude Desktop.

📖 New to MemoGraph MCP? See the [MCP User Guide](docs/MCP_USER_GUIDE.md) for practical usage instructions and examples!

🚨 Having connection issues? See [Setup & Troubleshooting Guide](docs/MCP_SETUP_TROUBLESHOOTING.md) - Common fixes for "cannot connect" errors!

19 Available Tools

Quick Setup for Cline

Add to your ~/.cline/mcp_settings.json:

{
  "mcp": {
    "servers": {
      "memograph": {
        "command": "python",
        "args": ["-m", "memograph.mcp.run_server"],
        "env": {
          "MEMOGRAPH_VAULT": "/path/to/your/vault"
        }
      }
    }
  }
}

Quick Setup for Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "memograph": {
      "command": "python",
      "args": ["-m", "memograph.mcp.run_server", "--vault", "/path/to/your/vault"]
    }
  }
}

Install from MCP Registry

NEW: MemoGraph is now available in the official MCP Registry! 🎉

Registry URL: https://github.com/modelcontextprotocol/servers/tree/main/src/memograph

#### Step 1: Install MemoGraph

First, install the Python package:

pip install memograph

#### Step 2: Configure in Your MCP Client

The MCP Registry provides the configuration template. Add to your client's config file:

For Cline (~/.cline/mcp_settings.json):

{
  "mcp": {
    "servers": {
      "memograph": {
        "command": "python",
        "args": ["-m", "memograph.mcp.run_server"],
        "env": {
          "MEMOGRAPH_VAULT": "/path/to/your/vault"
        }
      }
    }
  }
}

For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "memograph": {
      "command": "python",
      "args": ["-m", "memograph.mcp.run_server"],
      "env": {
        "MEMOGRAPH_VAULT": "/path/to/your/vault"
      }
    }
  }
}

Benefits of MCP Registry Listing:

• ✅ Official registry backed by Anthropic, GitHub, and Microsoft
• ✅ Discoverable by all MCP-compatible clients
• ✅ Verified server card and metadata
• ✅ Direct link from PyPI package
• ✅ Trusted by the MCP community

Note: The registry uses the PyPI package version. When you pip install memograph, you automatically get the latest registry-listed version.

See [MCP_REGISTRY_GUIDE.md](docs/MCP_REGISTRY_GUIDE.md) for complete submission and configuration guide.

Usage Examples

Once configured, use natural language with your AI assistant:

"Search my vault for memories about Python"
"Create a memory titled 'Project Ideas' with content '...'"
"Update memory abc-123 to have salience 0.9"
"Delete memory xyz-456"
"What tools are available?"
"Get vault statistics"

See [CONFIG_REFERENCE.md](memograph/mcp/CONFIG_REFERENCE.md) for complete MCP configuration guide.

Using Auto-Save Hooks

MemoGraph provides autonomous hooks to save conversations automatically:

• ⚠️ Important: Hooks are passive tools - see Autonomous Hooks Guide for setup
• 📝 Quick fix: Add custom instructions to Claude Desktop (instructions in guide)
• 🔧 Configure with MEMOGRAPH_AUTONOMOUS_MODE=true

Read the full Autonomous Hooks User Guide →

🎯 CLI Usage

MemoGraph comes with a powerful CLI for managing your vault and chatting with it.

Ingest

Index your markdown files into the graph database:

memograph --vault ~/my-vault ingest

Force re-indexing all files:

memograph --vault ~/my-vault ingest --force

Remember

Quickly add a memory from the command line:

memograph --vault ~/my-vault remember \
    --title "Team Sync" \
    --content "Discussed Q3 goals." \
    --tags planning q3

Context Window

Generate context for a query:

memograph --vault ~/my-vault context \
    --query "What did we decide about the database?" \
    --tags architecture \
    --depth 2 \
    --top-k 5

Ask (Interactive Chat)

Start an interactive chat session with your vault context:

memograph --vault ~/my-vault ask --chat --provider ollama --model llama3

Or ask a single question:

memograph --vault ~/my-vault ask \
    --query "Summarize our design decisions" \
    --provider claude \
    --model claude-3-5-sonnet-20240620

Diagnostics

Check your environment and connection to LLM providers:

memograph --vault ~/my-vault doctor

### Import Documents

Import documents (TXT, PDF, DOCX) and convert them to markdown:

Import a single file

memograph --vault ~/my-vault import document.pdf --type episodic

Import entire folder

memograph --vault ~/my-vault import ~/Documents --recursive

Preview files without importing (dry run)

memograph --vault ~/my-vault import ~/Documents --dry-run

Auto-ingest after import

memograph --vault ~/my-vault import document.pdf --auto-ingest

### Batch Operations

Efficiently manage multiple memories at once:

Bulk create memories from JSON/CSV

memograph --vault ~/my-vault batch-create memories.json

Bulk update memories by filter

memograph --vault ~/my-vault batch-update \ --filter-tags outdated \ --add-tags reviewed \ --salience 0.8

Bulk delete with safety checks

memograph --vault ~/my-vault batch-delete \ --filter-type episodic \ --filter-max-salience 0.3 \ --dry-run

### Data Management

Export, backup, and restore your vault:

Export vault to JSON/CSV/Markdown

memograph --vault ~/my-vault export --format json --output backup.json

Create timestamped backup

memograph --vault ~/my-vault backup --output ./backups

Restore from backup

memograph --vault ~/my-vault import-backup backup.zip

### Configuration & Statistics

Manage settings and view vault analytics:

View vault statistics

memograph --vault ~/my-vault stats

Configure settings

memograph config set embedding_provider openai memograph config get embedding_provider memograph config list

Manage profiles

memograph config profile create work --vault ~/work-vault memograph config profile use work

### MCP Setup

Interactive wizard to configure MCP server for Claude Desktop or Cline:

Run interactive setup wizard

memograph setup-mcp

Verify MCP configuration

memograph verify-mcp

**📖 Complete CLI Documentation:** See **[CLI Usage Guide](MEMOGRAPH_CLI_USAGE_GUIDE.md)** for detailed documentation with 200+ examples covering all 24 commands.

### 🤖 AI Features

MemoGraph includes powerful AI-powered features to enhance your knowledge management workflow. See **[AI Features Guide](docs/guides/AI_FEATURES.md)** for complete documentation.

#### 🏷️ AutoTagger - Intelligent Tag Suggestions

Automatically suggest relevant tags using semantic analysis, content structure, and existing patterns:

Suggest tags for a note

memograph suggest-tags note.md

Apply high-confidence suggestions automatically

memograph suggest-tags note.md --apply

Adjust confidence threshold and limit

memograph suggest-tags note.md --min-confidence 0.5 --max-suggestions 10

**Features:** Frequency-based extraction • Semantic similarity • Structure detection • Pattern learning • Confidence scoring

#### 🔗 LinkSuggester - Smart Wikilink Recommendations

Intelligently recommend wikilinks to related notes using semantic similarity and graph analysis:

Suggest links for a note

memograph suggest-links note.md

Apply suggestions automatically

memograph suggest-links note.md --apply

Show bidirectional link opportunities

memograph suggest-links note.md --show-bidirectional

**Features:** Semantic search • Keyword matching • Graph-based suggestions • Bidirectional detection • Target previews

#### 🔍 GapDetector - Knowledge Base Analysis

Identify missing topics, weak coverage, and isolated notes in your vault:

Detect all gaps

memograph detect-gaps

Focus on high-severity gaps

memograph detect-gaps --min-severity 0.7

Export results to JSON

memograph detect-gaps --output json > gaps.json

**Gap Types:** Missing Topics • Weak Coverage • Isolated Notes • Missing Links

#### 📊 Knowledge Analysis - Comprehensive Insights

Get comprehensive analysis of your entire knowledge base:

Full analysis with all features

memograph analyze-knowledge

Export detailed report to JSON

memograph analyze-knowledge --output json > analysis.json

**Analysis Includes:** Vault statistics • Topic clustering • Learning paths • Gap detection • Connection analysis

#### Python API for AI Features

from memograph import MemoryKernel from memograph.ai import AutoTagger, LinkSuggester, GapDetector

kernel = MemoryKernel("~/my-vault") kernel.ingest()

Get tag suggestions

tagger = AutoTagger(kernel, min_confidence=0.4) suggestions = await tagger.suggest_tags( content="Python is great for data science", title="Data Science with Python" )

Get link suggestions

suggester = LinkSuggester(kernel, min_confidence=0.5) links = await suggester.suggest_links( content="Python async programming tutorial", title="Async Python" )

Detect knowledge gaps

detector = GapDetector(kernel, min_severity=0.5) gaps = await detector.detect_gaps()

Comprehensive analysis

analysis = await detector.analyze_knowledge_base()

**📖 Complete Documentation:**
- **[AI Features Guide](docs/guides/AI_FEATURES.md)** - Comprehensive guide with examples
- **[Web UI Guide](docs/guides/WEB_UI_GUIDE.md)** - Using AI features in the browser
- **[MCP AI Tools Guide](docs/guides/MCP_AI_TOOLS.md)** - AI features for Claude & Cline

**💡 Use Cases:** Auto-organize notes • Discover connections • Identify gaps • Maintain consistency • Build learning paths

## 📖 Core Concepts

### Memory Types

MemoGraph supports different types of memories inspired by cognitive science:

- **Episodic**: Personal experiences and events (e.g., meeting notes)
- **Semantic**: Facts and general knowledge (e.g., documentation)
- **Procedural**: How-to knowledge and processes (e.g., tutorials)
- **Fact**: Discrete factual information (e.g., configuration values)

### Graph Traversal

The library uses BFS (Breadth-First Search) to traverse your knowledge graph:

Retrieve nodes with depth=2 (2 hops from seed nodes)

nodes = kernel.retrieve_nodes( query="graph algorithms", depth=2, # Traverse up to 2 levels deep top_k=10 # Return top 10 relevant memories )

### Salience Scoring

Each memory has a salience score (0.0-1.0) that represents its importance:

title: "Critical Architecture Decision" salience: 0.9 memory_type: semantic

We decided to use PostgreSQL for better ACID guarantees...

## 🏗️ Project Structure

MemoGraph/ ├── memograph/ # Main package │ ├── core/ # Core functionality │ │ ├── kernel.py # Memory kernel │ │ ├── graph.py # Graph implementation │ │ ├── retriever.py # Hybrid retrieval │ │ ├── indexer.py # File indexing │ │ └── parser.py # Markdown parsing │ ├── adapters/ # LLM and embedding adapters │ │ ├── embeddings/ # Embedding providers │ │ ├── frameworks/ # Framework integrations │ │ └── llm/ # LLM providers │ ├── storage/ # Storage and caching │ ├── mcp/ # MCP server implementation │ └── cli.py # CLI implementation ├── tests/ # Test suite ├── examples/ # Example usage └── scripts/ # Utility scripts

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

1. Clone the repository:

git clone https://github.com/Indhar01/MemoGraph.git cd MemoGraph

2. Install in development mode:

pip install -e ".[all,dev]"

3. Install pre-commit hooks:

pre-commit install

4. Run tests:

pytest

### Code Quality

We maintain high code quality standards:

- **Linting**: Ruff for fast Python linting
- **Formatting**: Ruff formatter for consistent code style
- **Type Checking**: MyPy for static type analysis
- **Testing**: Pytest with comprehensive test coverage
- **Pre-commit Hooks**: Automated checks before each commit

## 📚 Documentation

### Getting Started
- **[MCP User Guide](docs/MCP_USER_GUIDE.md)** - ⭐ **Start here!** Complete guide for using MemoGraph MCP
- **[Setup & Troubleshooting](docs/MCP_SETUP_TROUBLESHOOTING.md)** - 🚨 **Can't connect?** Step-by-step fixes for connection issues
- **[MCP Testing Guide](docs/MCP_TESTING_GUIDE.md)** - Testing your MCP server after setup

### For Developers & Contributors
- **[MCP Registry Guide](docs/MCP_REGISTRY_GUIDE.md)** - Publishing to official MCP Registry
- **[Versioning Strategy](docs/VERSIONING.md)** - Semantic versioning and release planning
- **[AGENTS.md](AGENTS.md)** - Guide for AI agents working with this codebase
- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project
- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines
- **[Security Policy](SECURITY.md)** - Security reporting and best practices
- **[Changelog](CHANGELOG.md)** - Version history and changes

## 🔒 Security

See our [Security Policy](SECURITY.md) for reporting vulnerabilities.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🌟 Acknowledgments

Inspired by the need for better memory management in LLM applications. Built with:

- Graph-based knowledge representation
- Hybrid retrieval strategies
- Cognitive science principles

## 📬 Contact & Support

- **Issues**: [GitHub Issues](https://github.com/Indhar01/MemoGraph/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Indhar01/MemoGraph/discussions)

## 📣 Community & Feedback

We value community feedback and contributions! Here's how to get involved:

### Report Issues
Found a bug or have a feature request? [Open an issue](https://github.com/Indhar01/MemoGraph/issues/new) on GitHub.

### Discussions
Join the conversation in [GitHub Discussions](https://github.com/Indhar01/MemoGraph/discussions):
- Ask questions
- Share use cases
- Suggest improvements
- Show what you've built

### Contributing
We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details on:
- Code contributions
- Documentation improvements
- Bug reports and feature requests
- Community support

### Stay Updated
- ⭐ Star the repository on [GitHub](https://github.com/Indhar01/MemoGraph)
- 👁️ Watch for updates and releases
- 📦 Follow the project on [PyPI](https://pypi.org/project/memograph/)
- 🔗 Check out the [MCP Registry listing](https://github.com/modelcontextprotocol/servers/tree/main/src/memograph)

## 🚦 Status

**Current Version**: 0.1.1 (Alpha - Marketplace Ready)

This project is in active development with a focus on code quality and stability:

- ✅ Core functionality is stable and tested
- ✅ All linter checks passing (Ruff)
- ✅ Type checking configured (MyPy)
- ✅ Pre-commit hooks enabled
- ✅ Comprehensive test suite
- ⚠️ API may change in minor versions until v1.0.0

**Recent Improvements**:
- 🎉 **Published to official MCP Registry** ([io.github.indhar01/memograph](https://github.com/modelcontextprotocol/servers/tree/main/src/memograph))
- 📦 **Version 0.1.1 Released** with registry integration improvements
- Enhanced code quality with Ruff linting and formatting
- Added comprehensive type checking with MyPy
- Improved project structure and organization
- Updated MCP server with 19 tools including autonomous features and graph operations
- Added AGENTS.md for AI assistant integration
- Created comprehensive MCP Registry submission guide
- Improved documentation with accurate installation instructions

---

Made with ❤️ for better LLM memory management