{"repo": "chasepassion/neuramem", "files": {"API.md": {"449cc149364516a6fc54940254a2064293246318": {"t": 1785747212.5647874, "n": 4551, "h": "2b201df82369e2f8", "c": "# NeuraMem API Documentation\n\nNeuraMem 记忆系统 REST API 接口文档。\n\n## 快速开始\n\n```bash\n# 启动服务\ncd e:\\code\\NeuraMem\nuvicorn src.api.main:app --reload --port 8000\n\n# 访问文档\n# Swagger UI: http://localhost:8000/docs\n# ReDoc: http://localhost:8000/redoc\n```\n\n---\n\n## API 端点\n\n### 健康检查\n\n#### `GET /v1/health`\n\n检查服务状态。\n\n**Response** `200 OK`\n```json\n{\n  \"status\": \"ok\",\n  \"version\": \"1.0.0\"\n}\n```\n\n---\n\n### 对话 (SSE 流式)\n\n#### `POST /v1/chat`\n\n基于记忆增强的流式对话接口，返回 Server-Sent Events。\n\n**Request Body**\n```json\n{\n  \"user_id\": \"string\",      // 必填：用户标识\n  \"chat_id\": \"string\",      // 必填：对话标识\n  \"message\": \"string\",      // 必填：用户消息\n  \"history\": [              // 可选：历史消息\n    {\"role\": \"user\", \"content\": \"...\"},\n    {\"role\": \"assistant\", \"content\": \"...\"}\n  ]\n}\n```\n\n**Response** `200 OK` (text/event-stream)\n\n```\ndata: {\"type\": \"chunk\", \"content\": \"你\"}\n\ndata: {\"type\": \"chunk\", \"content\": \"好\"}\n\ndata: {\"type\": \"done\", \"full_content\": \"你好，有什么可以帮您的吗？\"}\n\n```\n\n**SSE 事件类型**\n| type | 描述 |\n|------|------|\n| `chunk` | 流式 token |\n| `done` | 完成，包含完整回复 |\n| `error` | 错误信息 |\n\n**前端示例 (JavaScript)**\n```javascript\nconst response = await fetch('/v1/chat', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    user_id: 'user123',\n    chat_id: 'chat456',\n    message: '你好'\n  })\n});\n\nconst reader = response.body.getReader();\nconst decoder = new TextDecoder();\n\nwhile (true) {\n  const { done, value } = await reader.read();\n  if (done) break;\n  \n  const lines = decoder.decode(value).split('\\n');\n  for (const line of lines) {\n    if (line.startsWith('data: ')) {\n      const data = JSON.parse(line.slice(6));\n      if (data.type === 'chunk') {\n        console.log(data.content);\n      }\n    }\n  }\n}\n```\n\n---\n\n### 记忆管理\n\n#### `POST /v1/memories/manage`\n\n根据对话内容智能管理记忆（添加/更新/删除）。\n\n**Request Body**\n```json\n{\n  \"user_id\": \"string\",        // 必填：用户标识\n  \"chat_id\": \"string\",        // 必填：对话标识\n  \"user_text\": \"string\",      // 必填：用户输入\n  \"assistant_text\": \"string\"  // 必填：助手回复\n}\n```\n\n**Response** `200 OK`\n```json\n{\n  \"added_ids\": [123, 124],\n  \"success\": true\n}\n```\n\n---\n\n#### `POST /v1/memories/search`\n\n搜索用户相关记忆，支持叙事组扩展。\n\n**Request Body**\n```json\n{\n  \"user_id\": \"string\",  // 必填：用户标识\n  \"query\": \"string\"     // 必填：搜索内容\n}\n```\n\n**Response** `200 OK`\n```json\n{\n  \"episodic\": [\n    {\n      \"id\": 123,\n      \"user_id\": \"user123\",\n      \"memory_type\": \"episodic\",\n      \"ts\": 1702233600,\n      \"chat_id\": \"chat456\",\n      \"text\": \"用户说他是北京大学的学生\",\n      \"group_id\": 5\n    }\n  ],\n  \"semantic\": [\n    {\n      \"id\": 456,\n      \"user_id\": \"user123\",\n      \"memory_type\": \"semantic\",\n      \"ts\": 1702233700,\n      \"chat_id\": \"chat456\",\n      \"text\": \"用户是北京大学计算机系的学生\",\n      \"group_id\": -1\n    }\n  ]\n}\n```\n\n---\n\n#### `DELETE /v1/memories/{memory_id}`\n\n删除单条记忆。\n\n**Path Parameters**\n- `memory_id` (int): 记忆 ID\n\n**Query Parameters**\n- `user_id` (string, **必填**): 用户标识（用于所有权验证）\n\n**Example**\n```bash\nDELETE /v1/memories/123?user_id=user123\n```\n\n**Response** `200 OK`\n```json\n{\n  \"success\": true,\n  \"deleted_count\": 1\n}\n```\n\n**Error Response** `404 Not Found`\n```json\n{\n  \"error_code\": \"MEMORY_NOT_FOUND\",\n  \"detail\": \"Memory with id 123 not found\"\n}\n```\n\n---\n\n#### `DELETE /v1/memories/reset`\n\n删除用户的所有记忆。\n\n**Request Body**\n```json\n{\n  \"user_id\": \"string\"  // 必填：用户标识\n}\n```\n\n**Response** `200 OK`\n```json\n{\n  \"success\": true,\n  \"deleted_count\": 42\n}\n```\n\n---\n\n#### `POST /v1/memories/consolidate`\n\n触发记忆整合，从情景记忆中提取语义事实。\n\n**Request Body**\n```json\n{\n  \"user_id\": \"string\"  // 可选：指定用户，空则整合所有\n}\n```\n\n**Response** `200 OK`\n```json\n{\n  \"memories_processed\": 15,\n  \"semantic_created\": 3\n}\n```\n\n---\n\n## 错误码\n\n| HTTP Status | Error Code | 描述 |\n|-------------|------------|------|\n| 404 | `MEMORY_NOT_FOUND` | 记忆不存在或无权访问 |\n| 502 | `LLM_SERVICE_ERROR` | LLM 服务不可用 |\n| 503 | `DB_CONNECTION_ERROR` | 数据库连接失败 |\n| 500 | `INTERNAL_ERROR` | 内部错误 |\n\n---\n\n## 数据模型\n\n### MemoryResponse\n\n```typescript\ninterface MemoryResponse {\n  id: number;           // 记忆 ID\n  user_id: string;      // 用户标识\n  memory_type: string;  // \"episodic\" | \"semantic\"\n  ts: number;           // Unix 时间戳\n  chat_id: string;      // 对话标识\n  text: string;         // 记忆内容\n  group_id: number;     // 叙事组 ID，-1 表示未分组\n}\n```\n\n### ChatMessage\n\n```typescript\ninterface ChatMessage {\n  role: \"user\" | \"assistant\";\n  content: string;\n}\n```\n\n---\n\n## 配置环境变量\n\n```bash\n# API 配置\nAPI_HOST=0.0.0.0\nAPI_PORT=8000\nCORS_ORIGINS=http://localhost:3000,http://localhost:8080\n\n# 数据库\nMILVUS_URL=http://localhost:19530\n\n# LLM\nDEEPSEEK_API_KEY=your_api_key\nDEEPSEEK_BASE_URL=https://api.deepseek.com\n\n# Embedding\nSILICONFLOW_API_KEY=your_api_key\n```\n"}, "ddf405155a0978e387aa7d8a97583e744e19c96a": {"t": 1785771399.4304254, "n": 4551, "h": "2b201df82369e2f8", "c": "# NeuraMem API Documentation\n\nNeuraMem 记忆系统 REST API 接口文档。\n\n## 快速开始\n\n```bash\n# 启动服务\ncd e:\\code\\NeuraMem\nuvicorn src.api.main:app --reload --port 8000\n\n# 访问文档\n# Swagger UI: http://localhost:8000/docs\n# ReDoc: http://localhost:8000/redoc\n```\n\n---\n\n## API 端点\n\n### 健康检查\n\n#### `GET /v1/health`\n\n检查服务状态。\n\n**Response** `200 OK`\n```json\n{\n  \"status\": \"ok\",\n  \"version\": \"1.0.0\"\n}\n```\n\n---\n\n### 对话 (SSE 流式)\n\n#### `POST /v1/chat`\n\n基于记忆增强的流式对话接口，返回 Server-Sent Events。\n\n**Request Body**\n```json\n{\n  \"user_id\": \"string\",      // 必填：用户标识\n  \"chat_id\": \"string\",      // 必填：对话标识\n  \"message\": \"string\",      // 必填：用户消息\n  \"history\": [              // 可选：历史消息\n    {\"role\": \"user\", \"content\": \"...\"},\n    {\"role\": \"assistant\", \"content\": \"...\"}\n  ]\n}\n```\n\n**Response** `200 OK` (text/event-stream)\n\n```\ndata: {\"type\": \"chunk\", \"content\": \"你\"}\n\ndata: {\"type\": \"chunk\", \"content\": \"好\"}\n\ndata: {\"type\": \"done\", \"full_content\": \"你好，有什么可以帮您的吗？\"}\n\n```\n\n**SSE 事件类型**\n| type | 描述 |\n|------|------|\n| `chunk` | 流式 token |\n| `done` | 完成，包含完整回复 |\n| `error` | 错误信息 |\n\n**前端示例 (JavaScript)**\n```javascript\nconst response = await fetch('/v1/chat', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    user_id: 'user123',\n    chat_id: 'chat456',\n    message: '你好'\n  })\n});\n\nconst reader = response.body.getReader();\nconst decoder = new TextDecoder();\n\nwhile (true) {\n  const { done, value } = await reader.read();\n  if (done) break;\n  \n  const lines = decoder.decode(value).split('\\n');\n  for (const line of lines) {\n    if (line.startsWith('data: ')) {\n      const data = JSON.parse(line.slice(6));\n      if (data.type === 'chunk') {\n        console.log(data.content);\n      }\n    }\n  }\n}\n```\n\n---\n\n### 记忆管理\n\n#### `POST /v1/memories/manage`\n\n根据对话内容智能管理记忆（添加/更新/删除）。\n\n**Request Body**\n```json\n{\n  \"user_id\": \"string\",        // 必填：用户标识\n  \"chat_id\": \"string\",        // 必填：对话标识\n  \"user_text\": \"string\",      // 必填：用户输入\n  \"assistant_text\": \"string\"  // 必填：助手回复\n}\n```\n\n**Response** `200 OK`\n```json\n{\n  \"added_ids\": [123, 124],\n  \"success\": true\n}\n```\n\n---\n\n#### `POST /v1/memories/search`\n\n搜索用户相关记忆，支持叙事组扩展。\n\n**Request Body**\n```json\n{\n  \"user_id\": \"string\",  // 必填：用户标识\n  \"query\": \"string\"     // 必填：搜索内容\n}\n```\n\n**Response** `200 OK`\n```json\n{\n  \"episodic\": [\n    {\n      \"id\": 123,\n      \"user_id\": \"user123\",\n      \"memory_type\": \"episodic\",\n      \"ts\": 1702233600,\n      \"chat_id\": \"chat456\",\n      \"text\": \"用户说他是北京大学的学生\",\n      \"group_id\": 5\n    }\n  ],\n  \"semantic\": [\n    {\n      \"id\": 456,\n      \"user_id\": \"user123\",\n      \"memory_type\": \"semantic\",\n      \"ts\": 1702233700,\n      \"chat_id\": \"chat456\",\n      \"text\": \"用户是北京大学计算机系的学生\",\n      \"group_id\": -1\n    }\n  ]\n}\n```\n\n---\n\n#### `DELETE /v1/memories/{memory_id}`\n\n删除单条记忆。\n\n**Path Parameters**\n- `memory_id` (int): 记忆 ID\n\n**Query Parameters**\n- `user_id` (string, **必填**): 用户标识（用于所有权验证）\n\n**Example**\n```bash\nDELETE /v1/memories/123?user_id=user123\n```\n\n**Response** `200 OK`\n```json\n{\n  \"success\": true,\n  \"deleted_count\": 1\n}\n```\n\n**Error Response** `404 Not Found`\n```json\n{\n  \"error_code\": \"MEMORY_NOT_FOUND\",\n  \"detail\": \"Memory with id 123 not found\"\n}\n```\n\n---\n\n#### `DELETE /v1/memories/reset`\n\n删除用户的所有记忆。\n\n**Request Body**\n```json\n{\n  \"user_id\": \"string\"  // 必填：用户标识\n}\n```\n\n**Response** `200 OK`\n```json\n{\n  \"success\": true,\n  \"deleted_count\": 42\n}\n```\n\n---\n\n#### `POST /v1/memories/consolidate`\n\n触发记忆整合，从情景记忆中提取语义事实。\n\n**Request Body**\n```json\n{\n  \"user_id\": \"string\"  // 可选：指定用户，空则整合所有\n}\n```\n\n**Response** `200 OK`\n```json\n{\n  \"memories_processed\": 15,\n  \"semantic_created\": 3\n}\n```\n\n---\n\n## 错误码\n\n| HTTP Status | Error Code | 描述 |\n|-------------|------------|------|\n| 404 | `MEMORY_NOT_FOUND` | 记忆不存在或无权访问 |\n| 502 | `LLM_SERVICE_ERROR` | LLM 服务不可用 |\n| 503 | `DB_CONNECTION_ERROR` | 数据库连接失败 |\n| 500 | `INTERNAL_ERROR` | 内部错误 |\n\n---\n\n## 数据模型\n\n### MemoryResponse\n\n```typescript\ninterface MemoryResponse {\n  id: number;           // 记忆 ID\n  user_id: string;      // 用户标识\n  memory_type: string;  // \"episodic\" | \"semantic\"\n  ts: number;           // Unix 时间戳\n  chat_id: string;      // 对话标识\n  text: string;         // 记忆内容\n  group_id: number;     // 叙事组 ID，-1 表示未分组\n}\n```\n\n### ChatMessage\n\n```typescript\ninterface ChatMessage {\n  role: \"user\" | \"assistant\";\n  content: string;\n}\n```\n\n---\n\n## 配置环境变量\n\n```bash\n# API 配置\nAPI_HOST=0.0.0.0\nAPI_PORT=8000\nCORS_ORIGINS=http://localhost:3000,http://localhost:8080\n\n# 数据库\nMILVUS_URL=http://localhost:19530\n\n# LLM\nDEEPSEEK_API_KEY=your_api_key\nDEEPSEEK_BASE_URL=https://api.deepseek.com\n\n# Embedding\nSILICONFLOW_API_KEY=your_api_key\n```\n"}}}}