Metadata-Version: 2.4
Name: mindcore-memory
Version: 0.1.3
Summary: MCP Server for AI long-term memory and context management
Author-email: woshilaohei <1410770089@qq.com>
License: MIT
License-File: LICENSE
Keywords: agent,ai,context,llm,mcp,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: json-rpc>=1.5.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: structlog>=24.0.0
Requires-Dist: tinydb>=4.8.0
Provides-Extra: dev
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🧠 MindCore Memory MCP

**让 AI 记住一切，不再遗忘。生产级长期记忆 MCP Server。**

> "The best AI agent isn't the smartest — it's the one that remembers."

[![GitHub stars](https://img.shields.io/github/stars/woshilaohei/mindcore-memory-mcp?style=social)](https://github.com/woshilaohei/mindcore-memory-mcp/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
[![woshilaohei/mindcore-memory-mcp MCP server](https://glama.ai/mcp/servers/woshilaohei/mindcore-memory-mcp/badges/score.svg)](https://glama.ai/mcp/servers/woshilaohei/mindcore-memory-mcp)

## ⚡ 一句话价值

**MindCore Memory** 解决 AI Agent 最大痛点：上下文窗口有限、长对话信息丢失、跨session记忆断裂。

---

## 🎯 解决什么问题

| 痛点 | 现状 | MindCore Memory |
|------|------|----------------|
| AI 上下文忘性大 | 对话结束什么都忘 | ✅ 持久化长期记忆 |
| 跨session无法回忆 | 每次都重新教 | ✅ 跨会话知识复用 |
| 记忆混乱无优先级 | 所有记忆权重一样 | ✅ 重要性分级+置信度 |
| RAG暴力灌入 | 上下文过载质量下降 | ✅ 精准上下文窗口 |

---

## 🚀 3行上手

```bash
# 1. 安装
pip install mindcore-memory

# 2. 启动 MCP Server
mindcore-memory

# 3. 在你的 AI Agent 中调用
memory_id = memory_store("用户说他叫张三，周三有空")
context = memory_recall("用户的时间安排")
```

---

## 📊 Eval Framework 实测

```
✅ Storage Integrity:     100% (存储持久化正确)
✅ Recall Relevance:      100% (相关记忆优先召回)
✅ Confidence Calibration: 100% (置信度正确校准)
✅ Importance Weighting:  100% (高优先级记忆排名靠前)
✅ Context Efficiency:    100% (上下文窗口不过载)

Overall Score: 100%
```

---

## 📈 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=woshilaohei/mindcore-memory-mcp&type=Timeline)](https://star-history.com/#woshilaohei/mindcore-memory-mcp&Timeline)

---

## 🔧 核心工具

### `memory_store` - 存储记忆
```python
memory_store(
    content="Python是荷兰人Guido van Rossum创建的",
    importance=3,        # 1-4级重要性
    tags=["python", "history"],
    confidence=0.95,      # 置信度
    source="agent"       # agent/user/tool
)
```

### `memory_recall` - 召回记忆
```python
memory_recall(
    query="Python创始人是谁",
    tags=["python"],      # 可选标签过滤
    limit=10             # 返回数量
)
```

### `memory_context` - 构建上下文窗口
```python
# 为当前任务构建最优上下文（自动去重+优先级排序）
context = memory_context(
    query="当前项目状态",
    max_tokens=2000      # 自动截断
)
```

### `memory_stats` - 系统状态
```python
# 查看记忆统计：总数/分布/置信度
stats = memory_stats()
```

---

## 💰 开源说明

本项目为开源项目（MIT License），代码完全免费。存储层使用本地 JSON 文件，无云服务依赖，无数据收集。如需商业合作或定制开发，欢迎联系作者。

---

## 🤝 支持

如果 MindCore Memory 对你有帮助：

- ⭐ 给仓库点个 Star
- 🐛 提交 Issue 反馈问题
- 🔧 提交 PR 贡献代码

---

## 🏗️ 项目结构

```
mindcore-memory-mcp/
├── mindcore_memory/          # Python 包（pip install 入口）
│   ├── __init__.py
│   ├── memory_engine.py      # 核心记忆引擎
│   ├── server.py             # MCP Server（stdio+HTTP双传输）
│   ├── http_app.py           # HTTP端点（生产部署）
│   └── eval_framework.py     # 评测框架
├── tests/
│   └── test_memory.py        # 单元测试
├── examples/
│   └── basic_usage.py        # 使用示例
├── .github/workflows/
│   └── ci.yml                # CI/CD
├── pyproject.toml
├── README.md
└── LICENSE
```

---

## 🔌 集成方式

### Claude Desktop
```json
{
  "mcpServers": {
    "mindcore-memory": {
      "command": "pip",
      "args": ["install", "mindcore-memory"]
    }
  }
}
```

### VS Code AI
直接在扩展市场搜索 `MindCore Memory`。

### HTTP API（生产环境）
```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"memory_store","arguments":{"content":"test"}},"id":1}'
```

---

## 📐 生产级标准

| 标准 | 实现 |
|------|------|
| **JSON-RPC 2.0** | ✅ stdio + HTTP 双传输 |
| **Bearer Token认证** | ✅ HTTP端点可选认证 |
| **输入验证** | ✅ Pydantic schemas |
| **CI/CD** | ✅ GitHub Actions |
| **单元测试** | ✅ pytest + 覆盖率 |
| **Eval Framework** | ✅ 5项核心指标 |
| **可观测性** | ✅ structlog完整日志 |
| **用户数据主权** | ✅ JSONL本地文件，无vendor lock-in |

---

## 🤝 贡献

欢迎提交 Issue 和 PR！

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE)

---

---

<!-- mcp-name: io.github.woshilaohei/mindcore-memory -->


<p align="center">
  <strong>让 AI 拥有记忆，让人类更信任 AI。</strong>
</p>
