内容
# 记忆之熊 🐻
一款用于基于记忆的知识管理的智能MCP（模型上下文协议）服务器，具有实时文件监控和向量数据库集成。
## 概述
记忆之熊将您的markdown笔记转化为一个智能的、可搜索的知识库，AI助手可以与其无缝交互。它监控您的笔记目录，使用向量嵌入自动索引内容，并提供强大的搜索、创建和管理知识的工具。
### 主要功能
- 🔍 **语义搜索**：跨越整个笔记集合的基于向量的搜索
- 📝 **智能笔记创建**：具有结构化模板的AI辅助学习笔记生成
- 🃏 **闪存卡管理**：具有FSRS算法集成的间隔重复系统
- 👀 **实时监控**：在文件创建、修改或删除时自动索引
- 🏷️ **基于标签的组织**：使用灵活的标签过滤和组织笔记
- 🤖 **MCP集成**：与Claude等AI助手无缝集成
- 📊 **学习分析**：使用卡片统计数据和概览跟踪学习进度
## 安装
### 先决条件
- Python 3.10 或更高版本
- [uv](https://docs.astral.sh/uv/) 包管理器（推荐）或 pip
### 从PyPI安装
```bash
pip install memory-bear
```
### 从源码安装
```bash
git clone https://github.com/ag4852/memory-bear.git
cd memory-bear
uv sync
```
## 快速入门
### 1. 环境设置
在项目目录中创建 `.env` 文件：
```bash
# 必需：您的笔记目录
NOTES_DIR=/path/to/your/notes
# 可选：用于开发的测试笔记目录
TEST_NOTES_DIR=/path/to/test/notes
# 可选：用于高级嵌入的Hugging Face API密钥
HUGGINGFACE_API_KEY=your_hf_token_here
# 可选：自定义内容标签和主题
CONTENT_TAGS=lecture,homework,exam,concepts,research
SUBJECTS=math,science,history,general
# 可选：日志级别
LOG_LEVEL=INFO
```
### 2. 启动服务器
```bash
# 启动主MCP服务器
memory-bear --server
# 或以测试模式启动
memory-bear --test
```
### 3. 配置AI助手
将记忆之熊添加到AI助手的MCP配置中。对于Claude Desktop，请添加到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"memory-bear": {
"command": "memory-bear",
"args": ["--server"]
}
}
}
```
## 用法
### 可用工具
记忆之熊提供了几个AI助手可以使用的工具：
#### 📖 笔记管理
- **`search_notes`**：跨知识库的语义搜索
- **`create_study_note`**：使用模板生成结构化学习笔记
- **`edit_study_note`**：修改现有的学习笔记
- **`find_best_match`**：为给定查询找到最相关的笔记
#### 🃏 闪存卡系统
- **`create_cards_from_note`**：从学习笔记中生成闪存卡
- **`get_cards`**：检索用于学习会话的闪存卡
- **`get_cards_overview`**：查看统计数据和进度
- **`update_card`**：记录学习会话结果以进行间隔重复
#### 📚 牌堆管理
- **`archive_deck`**：存档已完成或未使用的牌堆
- **`unarchive_deck`**：恢复存档的牌堆
- **`delete_deck`**：永久删除牌堆
### 示例交互
```
用户：“搜索有关机器学习算法的笔记”
AI：使用search_notes工具查找相关内容
用户：“创建关于神经网络的学习笔记”
AI：使用create_study_note工具生成结构化内容
用户：“显示我的闪存卡以供复习”
AI：使用get_cards工具检索到期卡片以供学习
```
## 笔记格式
记忆之熊使用包含前置元数据的markdown文件：
```markdown
---
title: "机器学习基础"
subject: "computer-science"
tags: ["ml", "algorithms", "neural-networks"]
---
### 回忆提示
- 什么是监督学习？
- 神经网络如何处理信息？
- 机器学习有哪些主要类型？
---
### 关键概念
**监督学习**：一种机器学习类型，其中...
**神经网络**：受...
```
## 配置
### 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `NOTES_DIR` | 笔记目录的路径 | 必需 |
| `TEST_NOTES_DIR` | 测试笔记的路径 | 可选 |
| `HUGGINGFACE_API_KEY` | HF嵌入的API密钥 | 可选 |
| `CONTENT_TAGS` | 以逗号分隔的内容标签列表 | `lecture,homework,exam,concepts,research` |
| `SUBJECTS` | 以逗号分隔的主题列表 | `general` |
| `LOG_LEVEL` | 日志详细程度 | `INFO` |
| `TEST_MODE` | 启用测试模式 | `False` |
### 数据库
记忆之熊使用 [Weaviate](https://weaviate.io/) 作为其向量数据库，在本地运行并提供：
- 自动文本向量化
- 语义搜索能力
- 实时索引
- 元数据过滤
## 架构
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Markdown │ │ 文件监视器 │ │ Weaviate │
│ 笔记 │───▶│ （Watchdog） │───▶│ 向量数据库 │
│ 目录 │ │ │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
┌─────────────────┐ ┌──────────────────┐ │
│ AI 助手 │◀──▶│ MCP 服务器 │◀──────────┘
│ （Claude等） │ │ （FastMCP） │
└─────────────────┘ └──────────────────┘
```
### 组件
- **文件监视器**：使用Watchdog监控笔记目录中的更改
- **向量数据库**：用于语义搜索和存储的Weaviate实例
- **MCP 服务器**：基于FastMCP的服务器，向AI助手公开工具
- **同步引擎**：保持文件系统和数据库同步
- **FSRS 集成**：用于优化学习的间隔重复算法
## 开发
### 设置开发环境
```bash
git clone https://github.com/ag4852/memory-bear.git
cd memory-bear
uv sync --dev
```
### 运行测试
```bash
# 运行测试套件
uv run pytest
# 运行覆盖率测试
uv run pytest --cov=memory_bear
# 测试文件监视器
memory-bear --test
```
### 项目结构
```
src/memory_bear/
├── main.py # 入口点
├── server.py # MCP服务器设置
├── config.py # 配置管理
├── database/ # Weaviate集成
├── tools/ # MCP工具实现
├── utils/ # 实用函数
├── watcher/ # 文件监控系统
└── templates/ # 笔记模板
```
## 贡献
1. 复刻仓库
2. 创建功能分支（`git checkout -b feature/amazing-feature`）
3. 提交更改（`git commit -m 'Add amazing feature'`）
4. 推送到分支（`git push origin feature/amazing-feature`）
5. 打开拉取请求
## 故障排除
### 常见问题
**服务器无法启动**：检查您的 `NOTES_DIR` 是否存在且可访问。
**笔记未索引**：验证文件权限并检查日志中的Weaviate连接问题。
**搜索无结果**：确保笔记具有正确的元数据和内容。
**MCP连接失败**：验证AI助手的MCP配置。
### 日志记录
启用调试日志记录进行故障排除：
```bash
LOG_LEVEL=DEBUG memory-bear --server
```
## 许可证
该项目根据MIT许可证授权 - 参见 [LICENSE](LICENSE) 文件了解详情。
## 致谢
- 使用 [FastMCP](https://github.com/jlowin/fastmcp) 进行MCP服务器功能
- 使用 [Weaviate](https://weaviate.io/) 进行向量数据库功能
- 实现 [FSRS](https://github.com/open-spaced-repetition/fsrs4anki) 进行间隔重复
- 文件监控由 [Watchdog](https://github.com/gorakhargosh/watchdog) 驱动
## 链接
- [GitHub 仓库](https://github.com/ag4852/memory-bear)
- [问题跟踪器](https://github.com/ag4852/memory-bear/issues)
- [MCP 文档](https://modelcontextprotocol.io/)
