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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Memory Bear