语义记忆服务

存储器MCP

一种模型上下文协议（MCP）服务器，为AI助手提供持久的语义记忆。由...支持 图尔索 （libSQL）用于矢量搜索存储，以及 开放人工智能 用于嵌入和LLM驱动的查询生成。

所有互动都是用简单的英语进行的。服务器使用GPT-5和函数调用将自然语言自动转换为正确的数据库操作。

特性

• 记住 --通过自动重复检测、字段提取和质量验证存储新内存
• 忘记 --通过描述要更改的内容来删除或修改记忆
• 召回 --在不修改数据的情况下，通过语义或结构化查询搜索内存
• 过程 --审查和优化存储的记忆：合并重复项，填补空白，提出澄清问题
• 拒收系统 --LLM将拒绝具有结构化原因和类别的无意义、重复、矛盾或低质量的记忆
• 向量搜索 --使用OpenAI嵌入（文本嵌入-3小，1536维）和libSQL DiskANN索引进行语义相似性搜索
• 表隔离 --每个用例都有自己的表，表中有自定义的自由列，所有列都在一个数据库中
• Claude代码集成 --用于表管理的Slash命令(/setup-table, /list-tables, /drop-table)

运作原理

┌─────────────┐     plain English      ┌─────────────┐     function calls     ┌───────────┐
│  MCP Client │ ──────────────────────► │   GPT-5     │ ──────────────────────► │  Turso DB │
│  (Claude)   │ ◄────────────────────── │  + prompts  │ ◄────────────────────── │  (libSQL) │
└─────────────┘     structured result   └─────────────┘     SQL + vectors      └───────────┘

1. MCP客户端发送一个简单的英文请求（例如，“记住用户octocat更喜欢简洁的回复”）
2. 服务器加载表模式，并构建一个包含特定操作指令的系统提示
3. GPT-5决定调用哪些内部工具（搜索、插入、更新、删除、拒绝或提问）
4. 代理循环对Turso执行工具调用，将结果反馈给LLM，并重复最多5轮
5. 最终响应将返回给MCP客户端，并显示成功/拒绝/问题状态

建筑

src/
├── index.ts           # MCP server entry point — tool definitions
├── llm.ts             # OpenAI wrapper — models, tool schemas, prompt loading
├── memory-ops.ts      # Agentic loop — tool execution, rejection, questions
├── db.ts              # Turso/libSQL client — queries, schema inspection
├── embeddings.ts      # OpenAI embeddings — text-embedding-3-small
├── table-setup.ts     # Table lifecycle — create, drop, list
└── prompts/
    ├── base.txt       # Shared context (table schema, column descriptions)
    ├── remember.txt   # Store operation instructions + rejection rules
    ├── forget.txt     # Delete/modify operation instructions
    ├── recall.txt     # Read-only search instructions
    └── process.txt    # Memory refinement and question-asking instructions

系统提示存储为纯文本文件，便于编辑和版本控制。他们使用 {{TABLE_NAME}} 和 {{TABLE_SCHEMA}} 在运行时被替换的占位符。

需求

• Node.js 18+
• A. 图尔索 数据库（或任何与libSQL兼容的端点）
• 一 开放人工智能 API密钥

安装

git clone <repo-url>
cd memory
npm install
npm run build

环境变量

创建一个 .env 文件（参见 .env.example):

TURSO_DATABASE_URL=libsql://your-db.turso.io
TURSO_AUTH_TOKEN=your-turso-auth-token
OPENAI_API_KEY=sk-your-openai-api-key

创建内存表

每个用例都需要自己的表。使用克劳德代码 /setup-table 用于交互式设置的命令，或以编程方式创建表：

import { createMemoryTable } from "./src/table-setup.js";

await createMemoryTable("github_users", [
  { name: "username", type: "TEXT" },
  { name: "category", type: "TEXT" },
  { name: "importance", type: "TEXT" },
]);

每个表都会自动获取这些核心列：

再加上您定义的任何自由列（TEXT、INTEGER或REAL）。

MCP服务器配置

添加到您的Claude Code MCP配置中(.claude/mcp.json 或类似）：

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/memory-mcp/build/index.js"],
      "env": {
        "TURSO_DATABASE_URL": "libsql://your-db.turso.io",
        "TURSO_AUTH_TOKEN": "your-token",
        "OPENAI_API_KEY": "sk-your-key"
      }
    }
  }
}

工具参考

remember

存储新内存。LLM首先搜索重复项，从上下文中提取自由形式的字段值，并可以拒绝错误的输入。

拒收类别： nonsensical, contradictory, duplicate, inappropriate, insufficient_detail, other

forget

删除或修改现有内存。先搜索，然后删除或更新匹配的条目。

recall

只读存储器检索。可以使用语义向量搜索、SQL查询或两者兼而有之。

process

回顾和完善现有的记忆。分析重复、空白和过时的条目。为用户返回澄清问题。

process_answers

跟进 process。回答它提出的问题，系统会应用这些改进。

处理工作流

这 process → process_answers 流程分为两个阶段：

第一阶段：分析 (process)

1. LLM从表中获取所有内存
2. 它识别重复、模糊条目、缺失字段和矛盾
3. 它产生了关于它们与哪些记忆相关的澄清问题
4. 问题被返回给调用者——还没有发生突变

第二阶段：完善 (process_answers)

1. 呼叫者提供问题的答案
2. LLM使用这些答案来合并重复项、更新模糊记忆、填写字段和删除过时的条目
3. 返回更改摘要

开发和测试

# Run unit tests (mocked, no API keys needed)
npm test

# Run integration tests (requires OPENAI_API_KEY)
npm run test:integration

# Run all tests
npm run test:all

# Development mode
npm run dev

# Build
npm run build

测试结构

• tests/db.test.ts --使用内存中的libSQL进行数据库操作
• tests/table-setup.test.ts --表创建、索引和生命周期
• tests/llm.test.ts --系统提示内容、每次操作的工具过滤、严格的模式模式模式验证
• tests/memory-ops.test.ts --代理循环、拒绝处理、进程突变保护、循环耗尽
• tests/integration/openai.test.ts -真正的OpenAI API调用测试工具选择、拒绝、多转弯流和严格的模式接受（跳过 OPENAI_API_KEY)

限制和安全注意事项

• SQL信任边界 --LLM生成SQL查询和筛选子句。当 sql_query 仅限于 SELECT 从理论上讲，该模型可以创建跨表读取或使用意外构造的查询。对于敏感部署，考虑添加架构级查询验证。
• 流程可扩展性 --The process 操作从表中获取所有内存。对于具有许多条目的表，这可能会达到令牌限制或变得缓慢。考虑批量处理大型表格。
• 提示注入 --由于LLM将用户输入解释为自然语言，对抗性输入可能会操纵工具选择。拒绝系统和每次操作的工具过滤可以缓解这种情况，但并不能消除它。
• 嵌入一致性 --记忆被嵌入 text-embedding-3-small改变嵌入模型需要重新嵌入所有现有的存储器。

Claude代码命令

在使用Claude Code在此仓库中工作时，可以使用以下命令：

• /setup-table <name> --根据您的用例，使用建议的列创建交互式表
• /list-tables --显示所有内存表、其模式和行数
• /drop-table <name> --删除内存表（先要求确认）