memograph 0.3.0

A graph-based memory system for LLMs with intelligent retrieval using knowledge graphs, hybrid search, and semantic embeddings

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 for practical usage instructions and examples!

🚨 Having connection issues? See Setup & Troubleshooting Guide - Common fixes for "cannot connect" errors!

19 Available Tools

Category	Tools	Description
Search	search_vault, query_with_context	Semantic search and context retrieval
Create	create_memory, import_document	Add memories and import documents
Read	list_memories, get_memory, get_vault_info	Browse and retrieve memories
Update	update_memory	Modify existing memories
Delete	delete_memory	Remove memories by ID
Analytics	get_vault_stats	Vault statistics and insights
Discovery	list_available_tools	List all available tools
Autonomous	auto_hook_query, auto_hook_response, configure_autonomous_mode, get_autonomous_config	Autonomous memory management
Graph	relate_memories, search_by_graph, find_path	Graph-native linking and traversal
Bulk	bulk_create	Create multiple memories in one call

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 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 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:

```bash
# 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 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 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 - Comprehensive guide with examples
• Web UI Guide - Using AI features in the browser
• MCP AI Tools Guide - 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 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 - ⭐ Start here! Complete guide for using MemoGraph MCP
• Setup & Troubleshooting - 🚨 Can't connect? Step-by-step fixes for connection issues
• MCP Testing Guide - Testing your MCP server after setup

For Developers & Contributors

• MCP Registry Guide - Publishing to official MCP Registry
• Versioning Strategy - Semantic versioning and release planning
• AGENTS.md - Guide for AI agents working with this codebase
• Contributing Guide - How to contribute to the project
• Code of Conduct - Community guidelines
• Security Policy - Security reporting and best practices
• Changelog - Version history and changes

🔒 Security

See our Security Policy for reporting vulnerabilities.

📄 License

This project is licensed under the MIT License - see the 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
• Discussions: GitHub 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 on GitHub.

Discussions

Join the conversation in GitHub Discussions:

• Ask questions
• Share use cases
• Suggest improvements
• Show what you've built

Contributing

We welcome contributions! See our Contributing Guide for details on:

• Code contributions
• Documentation improvements
• Bug reports and feature requests
• Community support

Stay Updated

• ⭐ Star the repository on GitHub
• 👁️ Watch for updates and releases
• 📦 Follow the project on PyPI
• 🔗 Check out the MCP Registry listing

🚦 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)
• 📦 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