# 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](https://docs.astral.sh/uv/) package manager (recommended) or pip

### Install from PyPI

```bash
pip install memory-bear
```

### Install from Source

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

```bash
# 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

```bash
# 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`:

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

```markdown
---
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](https://weaviate.io/) 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

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

### Running Tests

```bash
# 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:

```bash
LOG_LEVEL=DEBUG memory-bear --server
```

## License

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

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp) for MCP server functionality
- Uses [Weaviate](https://weaviate.io/) for vector database capabilities
- Implements [FSRS](https://github.com/open-spaced-repetition/fsrs4anki) for spaced repetition
- File monitoring powered by [Watchdog](https://github.com/gorakhargosh/watchdog)

## Links

- [GitHub Repository](https://github.com/ag4852/memory-bear)
- [Issue Tracker](https://github.com/ag4852/memory-bear/issues)
- [MCP Documentation](https://modelcontextprotocol.io/)