Metadata-Version: 2.4
Name: shared-memory-mcp
Version: 0.4.0
Summary: Cross-IDE shared memory MCP Server for AI Agents. Supports Kiro, Cursor, Windsurf, Trae and more.
License: MIT
License-File: LICENSE
Keywords: agent,ai,cross-ide,mcp,memory,shared-memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# shared-memory-mcp

跨 IDE 共享记忆的 MCP Server。支持 Kiro、Cursor、Windsurf、Trae 等多终端间的会话记忆共享。

Agent 自动判断写入时机，无需人工干预。使用 SQLite + FTS5，零外部依赖。

## 安装

```bash
# 方式一：uvx 直接运行（推荐，无需安装）
uvx shared-memory-mcp

# 方式二：pip 安装
pip install shared-memory-mcp
```

## 配置 MCP

### 方式一：uvx（推荐）

发布到 PyPI 后，在各 IDE 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "shared-memory": {
      "command": "uvx",
      "args": ["shared-memory-mcp"],
      "disabled": false,
      "autoApprove": ["memory_write", "memory_read", "memory_list", "memory_delete"]
    }
  }
}
```

### 方式二：本地源码运行

```json
{
  "mcpServers": {
    "shared-memory": {
      "command": "python",
      "args": ["-m", "shared_memory_mcp.server"],
      "env": {
        "PYTHONPATH": "D:\\github\\mcp-sharedMemory\\shared-memory-mcp\\src"
      },
      "disabled": false,
      "autoApprove": ["memory_write", "memory_read", "memory_list", "memory_delete"]
    }
  }
}
```

### 各 IDE 配置文件位置

| IDE | 项目级配置 | 全局配置 |
|-----|-----------|---------|
| Kiro | `.kiro/settings/mcp.json` | `~/.kiro/settings/mcp.json` |
| Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
| Windsurf | 对应 MCP 配置位置 | 对应全局配置 |
| Trae | 对应 MCP 配置位置 | 对应全局配置 |

## 配置 Steering 规则

在各 IDE 的全局规则中添加以下内容，让 Agent 自动读写记忆：

```markdown
## 共享记忆规则

### 项目标识
- project 参数使用「父级文件夹/当前文件夹」拼接，如果父级是磁盘根目录则只用当前文件夹名
  - 例：D:\github\my-app → project="github/my-app"
  - 例：D:\my-app → project="my-app"

### 会话开始
- 自动调用 memory_list(project="<当前项目名>") 获取记忆索引
- 如有相关记忆，调用 memory_read 获取最近关键记忆的摘要

### 自动写入时机
当你做出以下行为时，自动调用 memory_write 写入共享记忆：
- 架构决策（type="decision"）
- 阶段完成（type="milestone"）
- 重要结论（type="conclusion"）
- 项目上下文（type="context"）
- 问题方案（type="issue"）

### 用户手动触发
- "记住：..." / "记录：..." — 直接写入
- "记录上面的关键点" / "总结记录一下" — 回顾对话提取关键内容写入
- "记录上一轮对话" — 仅回顾上一个来回

### 不记录
- 简单问答、闲聊、临时调试等低价值信息
```

### 各 IDE 规则文件位置

| IDE | 全局规则路径 |
|-----|-------------|
| Kiro | `~/.kiro/steering/shared-memory.md` |
| Cursor | Cursor Settings → Rules → User Rules |

## 工具说明

| 工具 | 说明 | Token 消耗 |
|------|------|-----------|
| `memory_write` | 写入记忆，返回仅 id+status | 极低 |
| `memory_read` | 读取记忆，默认只返回摘要 | 低 |
| `memory_list` | 极简索引，每条一行 | 最低 |
| `memory_delete` | 删除过时记忆 | 极低 |

## 发布到 PyPI

### 前置条件

1. 注册 [PyPI](https://pypi.org/) 账号
2. 安装构建工具：

```bash
pip install build twine
```

### 构建与发布

```bash
# 进入项目目录
cd shared-memory-mcp

# 构建
python -m build

# 上传到 TestPyPI（先测试）
twine upload --repository testpypi dist/*

# 从 TestPyPI 测试安装
pip install --index-url https://test.pypi.org/simple/ shared-memory-mcp

# 确认无误后，上传到正式 PyPI
twine upload dist/*
```

### 发布后验证

```bash
# uvx 直接运行（无需安装）
uvx shared-memory-mcp

# 或 pip 安装后运行
pip install shared-memory-mcp
shared-memory-mcp
```

## 数据存储

- 数据库文件：`~/.shared-memory-mcp/memories.db`
- 所有 IDE 共享同一个 SQLite 数据库
- 使用 WAL 模式支持并发读取
- FTS5 全文搜索索引

## License

MIT
