npm package: @lakphy/talk-to-me
Description: A MCP Server that turns any Agent into a thoughtful personal assistant with memory.
Author: lakphy
Latest version: 0.0.1

# Talk to Me

一个 MCP (Model Context Protocol) Server，让任何 Agent 都能成为你的贴心私人助理。

## 设计理念

- **极简主义**: 使用 LibSQL (SQLite) 本地存储，无需复杂的向量数据库
- **原声保真**: 严格记录用户原话，不做任何润色或总结
- **历史留痕**: 软删除机制，保留完整的思维演变轨迹
- **智能回响**: 写入时自动关联历史记录，防止信息孤岛
- **语义交给 Agent**: 不依赖字符串检索，让 Agent 自己做语义理解

## 快速开始

### 安装

**方式 1: 全局安装（推荐）**

```bash
npm install -g @lakphy/talk-to-me
# 或
pnpm add -g @lakphy/talk-to-me
```

**方式 2: 使用 npx（无需安装）**

直接在 MCP 配置中使用 `npx` 调用。

**详细安装指南**: 查看 [INSTALL.md](./INSTALL.md)

### 配置

在你的 MCP 客户端（Claude Desktop 或 Cursor）配置文件中添加：

**使用全局安装：**

```json
{
  "mcpServers": {
    "talk-to-me": {
      "command": "talk-to-me"
    }
  }
}
```

**使用 npx（无需安装）：**

```json
{
  "mcpServers": {
    "talk-to-me": {
      "command": "npx",
      "args": ["-y", "@lakphy/talk-to-me"]
    }
  }
}
```

**配置文件位置**：

- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Cursor**: 在设置中搜索 "MCP"

## 数据存储

数据库文件位置遵循 XDG 规范：

- **macOS**: `~/Library/Application Support/talk-to-me/memory.db`
- **Linux**: `~/.local/share/talk-to-me/memory.db`
- **Windows**: `%APPDATA%/talk-to-me/memory.db`

## MCP 接口

### Tools

#### `capture_fragment`

捕获用户的想法、待办、目标等碎片信息。

```typescript
{
  content: string;      // 用户原话（红线：必须是原话）
  type: 'idea' | 'todo' | 'flag' | 'insight' | 'moment';
  tags?: string[];      // 标签
  keywords?: string[];  // 关键词
  mood?: string;        // 情绪
  energy_level?: number; // 精力水平 1-10
}
```

#### `remove_fragment`

软删除碎片记录（保留历史）。

```typescript
{
  id: string;      // 碎片 ID
  reason?: string; // 删除原因
}
```

#### `search_notes`

获取或搜索碎片记录。**推荐让 Agent 自己做语义筛选**。

```typescript
{
  keyword?: string;          // 搜索关键词（可选，不传返回全部）
  type?: 'idea' | 'todo' | 'flag' | 'insight' | 'moment'; // 按类型筛选
  include_deleted?: boolean; // 是否包含已删除记录，默认 true
  limit?: number;            // 返回数量限制，默认 100
}
```

**推荐用法**：不传 keyword，通过 type 筛选或直接获取全部，让 Agent 自己做语义理解：

```json
// 获取所有 flag
{ "type": "flag" }

// 获取全部记录
{ }
```

### Resources

#### `talk-to-me://context/now`

获取当前上下文快照，包含：

- 最近的碎片记录
- 活跃的待办事项
- 活跃的目标 (Flag)

#### `talk-to-me://fragments/all`

获取全部碎片记录（包含已删除），让 Agent 自己做语义理解和筛选。

### Prompts

#### `thoughtful_companion`

将 Agent 转变为贴心的私人助理，包含完整的系统指令：

- 原话记录红线
- 时间精确参考
- 软删除处理规则
- 智能回响使用指南

## 使用示例

### 场景 1: 记录想法

用户: "我想健身"

Agent 调用 `capture_fragment`:

```json
{
  "content": "我想健身",
  "type": "flag",
  "keywords": ["健身", "运动", "锻炼"]
}
```

### 场景 2: 查询 Flag

用户: "我立过什么 flag？"

Agent 调用 `search_notes`:

```json
{
  "type": "flag"
}
```

返回全部 flag 类型记录，Agent 自己做语义理解和组织回复。

### 场景 3: 放弃目标

用户: "健身太累了，算了"

Agent 调用 `remove_fragment`:

```json
{
  "id": "frag_xxx",
  "reason": "太累了"
}
```

### 场景 4: 回顾历史

用户: "我以前想做什么来着？"

Agent 调用 `search_notes`:

```json
{
  "include_deleted": true
}
```

Agent 拿到全部记录后，自己分析并回复：
"你之前想健身，不过在 x 月 x 日因为觉得太累而放弃了。"

## CLI 命令

安装后，可以通过以下方式调用：

```bash
# 直接运行（启动 MCP Server stdio 模式）
talk-to-me

# 或使用 npx（无需安装）
npx -y @lakphy/talk-to-me
```

**注意**: MCP Server 通过 stdio 协议通信，通常由 MCP 客户端（如 Claude Desktop、Cursor）自动调用，不需要手动运行。

## 本地开发

```bash
# 克隆项目
git clone <repo-url>
cd talk-to-me

# 安装依赖
pnpm install

# 开发模式（监听文件变化）
pnpm dev

# 构建
pnpm build

# 类型检查
pnpm typecheck

# 测试 CLI
./scripts/test-cli.sh
```

### 本地测试

如需本地测试，在 MCP 配置中使用绝对路径：

```json
{
  "mcpServers": {
    "talk-to-me": {
      "command": "node",
      "args": ["/Users/your-username/projects/talk-to-me/dist/index.mjs"]
    }
  }
}
```

## License

MIT