Memory Bear 🐻

An intelligent MCP (Model Context Protocol) server for memory-based knowledge management with real-time file monitoring and vector database integration.

Overview

Memory Bear transforms your markdown notes into an intelligent, searchable knowledge base that AI assistants can interact with seamlessly. It monitors your notes directory, automatically indexes content using vector embeddings, and provides powerful tools for searching, creating, and managing your knowledge.

Key Features

• 🔍 Semantic Search: Vector-based search across your entire note collection
• 📝 Smart Note Creation: AI-assisted study note generation with structured templates
• 🃏 Flashcard Management: Spaced repetition system with FSRS algorithm integration
• 👀 Real-time Monitoring: Automatic indexing when files are created, modified, or deleted
• 🏷️ Tag-based Organization: Filter and organize notes with flexible tagging
• 🤖 MCP Integration: Seamless integration with AI assistants like Claude
• 📊 Study Analytics: Track learning progress with card statistics and overviews

Installation

Prerequisites

• Python 3.10 or higher
• uv package manager (recommended) or pip

Install from PyPI

pip install memory-bear

Install from Source

git clone https://github.com/ag4852/memory-bear.git
cd memory-bear
uv sync

Quick Start

1. Environment Setup

Create a .env file in your project directory:

# Required: Your notes directory
NOTES_DIR=/path/to/your/notes

# Optional: Test notes directory for development
TEST_NOTES_DIR=/path/to/test/notes

# Optional: Hugging Face API key for advanced embeddings
HUGGINGFACE_API_KEY=your_hf_token_here

# Optional: Customize content tags and subjects
CONTENT_TAGS=lecture,homework,exam,concepts,research
SUBJECTS=math,science,history,general

# Optional: Logging level
LOG_LEVEL=INFO

2. Start the Server

# Start the main MCP server
memory-bear --server

# Or start in test mode
memory-bear --test

3. Configure Your AI Assistant

Add Memory Bear to your AI assistant's MCP configuration. For Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "memory-bear": {
      "command": "memory-bear",
      "args": ["--server"]
    }
  }
}

Usage

Available Tools

Memory Bear provides several tools that AI assistants can use:

📖 Note Management

• search_notes: Semantic search across your knowledge base
• create_study_note: Generate structured study notes with templates
• edit_study_note: Modify existing study notes
• find_best_match: Find the most relevant note for a given query

🃏 Flashcard System

• create_cards_from_note: Generate flashcards from study notes
• get_cards: Retrieve flashcards for study sessions
• get_cards_overview: View statistics and progress
• update_card: Record study session results for spaced repetition

📚 Deck Management

• archive_deck: Archive completed or unused decks
• unarchive_deck: Restore archived decks
• delete_deck: Permanently remove decks

Example Interactions

User: "Search for notes about machine learning algorithms"
AI: Uses search_notes tool to find relevant content

User: "Create a study note about neural networks"
AI: Uses create_study_note tool to generate structured content

User: "Show me my flashcards for review"
AI: Uses get_cards tool to retrieve due cards for study

Note Format

Memory Bear works with markdown files that include frontmatter metadata:

---
title: "Machine Learning Basics"
subject: "computer-science"
tags: ["ml", "algorithms", "neural-networks"]
---

### Recall Prompts
- What is supervised learning?
- How do neural networks process information?
- What are the main types of machine learning?

---

### Key Concepts

**Supervised Learning**: A type of machine learning where...

**Neural Networks**: Computational models inspired by...

Configuration

Environment Variables

Variable	Description	Default
NOTES_DIR	Path to your notes directory	Required
TEST_NOTES_DIR	Path for test notes	Optional
HUGGINGFACE_API_KEY	API key for HF embeddings	Optional
CONTENT_TAGS	Comma-separated list of content tags	lecture,homework,exam,concepts,research
SUBJECTS	Comma-separated list of subjects	general
LOG_LEVEL	Logging verbosity	INFO
TEST_MODE	Enable test mode	False

Database

Memory Bear uses Weaviate as its vector database, which runs locally and provides:

• Automatic text vectorization
• Semantic search capabilities
• Real-time indexing
• Metadata filtering

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Markdown      │    │   File Watcher   │    │   Weaviate      │
│   Notes         │───▶│   (Watchdog)     │───▶│   Vector DB     │
│   Directory     │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                        │
┌─────────────────┐    ┌──────────────────┐           │
│   AI Assistant  │◀──▶│   MCP Server     │◀──────────┘
│   (Claude, etc) │    │   (FastMCP)      │
└─────────────────┘    └──────────────────┘

Components

• File Watcher: Monitors notes directory for changes using Watchdog
• Vector Database: Weaviate instance for semantic search and storage
• MCP Server: FastMCP-based server exposing tools to AI assistants
• Sync Engine: Keeps filesystem and database in sync
• FSRS Integration: Spaced repetition algorithm for optimal learning

Development

Setup Development Environment

git clone https://github.com/ag4852/memory-bear.git
cd memory-bear
uv sync --dev

Running Tests

# Run the test suite
uv run pytest

# Run with coverage
uv run pytest --cov=memory_bear

# Test the file watcher
memory-bear --test

Project Structure

src/memory_bear/
├── main.py              # Entry point
├── server.py            # MCP server setup
├── config.py            # Configuration management
├── database/            # Weaviate integration
├── tools/               # MCP tool implementations
├── utils/               # Utility functions
├── watcher/             # File monitoring system
└── templates/           # Note templates

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Troubleshooting

Common Issues

Server won't start: Check that your NOTES_DIR exists and is accessible.

Notes not indexing: Verify file permissions and check logs for Weaviate connection issues.

Search returns no results: Ensure notes have proper frontmatter and content.

MCP connection fails: Verify your AI assistant's MCP configuration.

Logging

Enable debug logging for troubleshooting:

LOG_LEVEL=DEBUG memory-bear --server

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with FastMCP for MCP server functionality
• Uses Weaviate for vector database capabilities
• Implements FSRS for spaced repetition
• File monitoring powered by Watchdog

Links

• GitHub Repository
• Issue Tracker
• MCP Documentation