# https://github.com/aiming-lab/SimpleMem 项目说明书

生成时间：2026-07-10 23:37:18 UTC

## 目录

- [项目概述与系统架构](#page-1)
- [核心 API、记忆管线与检索机制](#page-2)
- [MCP 服务器、Docker 部署与后端集成](#page-3)
- [常见问题、复现指南、安全与社区议题](#page-4)

<a id='page-1'></a>

## 项目概述与系统架构

### 相关页面

相关主题：[核心 API、记忆管线与检索机制](#page-2), [MCP 服务器、Docker 部署与后端集成](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/aiming-lab/SimpleMem/blob/main/README.md)
- [simplemem/__init__.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/__init__.py)
- [simplemem/router.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/router.py)
- [simplemem_router.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem_router.py)
- [simplemem/text/system.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/text/system.py)
- [setup.py](https://github.com/aiming-lab/SimpleMem/blob/main/setup.py)
</details>

# 项目概述与系统架构

## 一、项目定位与设计目标

SimpleMem 是一个面向大语言模型（LLM）的**长时记忆（long-term memory）系统**，通过对原始对话与文档进行**语义无损压缩**与**意图感知检索（intent-aware retrieval）**，在显著降低 token 消耗的同时保持回答质量稳定。项目在 v0.3.0 版本中将原本分散的 SimpleMem（文本记忆）、Omni-SimpleMem（多模态记忆）与 EvolveMem（记忆演化机制）三条研发线合并为单一可发布包，使用者只需 `from simplemem import SimpleMem` 即可完成导入，后端则由首次调用的方法自动选择。资料来源：[README.md:1-40]()

项目的设计目标集中体现在以下三点：
- **语义无损压缩**：将历史对话或长文档压缩为高密度记忆条目，避免传统 RAG 切分后语义断裂的问题。
- **意图感知检索**：在检索阶段结合用户查询意图而非仅做表面相似度匹配，从而提升回答准确率。
- **多模态与可演化**：同一接口同时支持纯文本与多模态输入，并通过 EvolveMem 提供记忆条目的迭代精化能力。

## 二、整体系统架构

```mermaid
graph TB
  U[用户/调用方] --> S[simplemem.SimpleMem]
  S --> R[Router 路由层]
  R -- "add_text / search" --> T[Text 后端<br/>SimpleMem]
  R -- "add_image / multimodal API" --> M[Multimodal 后端<br/>Omni-SimpleMem]
  R -- "evolve / refine" --> E[EvolveMem]
  T --> V[(向量库 + 元数据)]
  M --> OM[OmniMemoryConfig]
  E --> V
```

整个软件包以 `simplemem/` 为顶层目录，子系统按后端维度划分。统一入口 `simplemem/__init__.py` 负责暴露对外 API（如 `SimpleMem`），`simplemem/router.py` 与 `simplemem_router.py` 则承担根据方法签名分发到不同后端的职责。资料来源：[simplemem/__init__.py:1-30]()、[simplemem/router.py:1-60]()

| 子系统 | 典型入口 | 用途 |
| --- | --- | --- |
| `simplemem.text` | `add_text / search` | 纯文本语义压缩与检索 |
| `simplemem.omni`（或 OmniSimpleMem 子模块） | `add_image / add_multimodal` | 图像与多模态输入 |
| `simplemem.evolve`（EvolveMem） | `evolve / refine_memory` | 记忆条目演化 |
| `database/vector_store.py` | `structured_search` | LanceDB 持久化 |

资料来源：[README.md:20-60]()、[simplemem/text/system.py:1-40]()

## 三、路由机制与配置

v0.3.0 的核心变化是引入**首次方法自动路由**：当用户首次调用 `add_text` 或 `search` 时，路由器锁定文本后端（SimpleMem）；若首次调用为多模态相关 API，则锁定 Omni-SimpleMem；EvolveMem 通常作为可叠加的精化层被显式调用。这一机制避免了在调用点反复传入后端参数的设计冗余。资料来源：[simplemem/router.py:1-80]()、`simplemem_router.py:1-50]()`

在配置层，曾经在 Omni-SimpleMem 单独发布期间出现 `omni_memory.core.config` 模块缺失的问题（参见 issue #49 与 #60），用户执行 `from omni_memory.core.config import OmniMemoryConfig` 时会因仓库中缺少对应 `config.py` 而抛错。v0.3.0 统一包通过将配置迁移至 `simplemem/config/` 命名空间，从路径层面消除了该问题，新安装可直接读取根级配置模块。资料来源：[simplemem/__init__.py:30-60]()

依赖与可安装性方面，`setup.py` 声明包名、入口点及外部依赖（如 `lancedb`、`langchain-openai` 等）。需要注意的是，社区已报告 `langchain-openai` 的旧版本存在 SSRF / DNS 重绑定漏洞（issue #57），在自部署环境中应锁定到已修复版本；此外 `database/vector_store.py` 中 `structured_search` 的 `.where()` 子句直接以 f-string 拼接用户派生的 person/entity 名称（issue #53），存在过滤注入风险，升级或修补时应优先转义与参数化处理。

## 四、与子系统的协作

文本主链路在 `simplemem/text/system.py` 中编排：原始输入经压缩后写入向量库，检索时结合意图理解与元数据过滤返回候选记忆。多模态链路沿用文本链路的检索语义，但扩展了对图像特征的处理。EvolveMem 可视为在两条链路之上的横切层，负责对长期沉淀的记忆条目进行再压缩、合并或淘汰。资料来源：[simplemem/text/system.py:40-120]()、`README.md:60-100]()

---

<a id='page-2'></a>

## 核心 API、记忆管线与检索机制

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [MCP 服务器、Docker 部署与后端集成](#page-3), [常见问题、复现指南、安全与社区议题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [simplemem/core/memory_builder.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/core/memory_builder.py)
- [simplemem/core/hybrid_retriever.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/core/hybrid_retriever.py)
- [simplemem/core/answer_generator.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/core/answer_generator.py)
- [simplemem/core/models/memory_entry.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/core/models/memory_entry.py)
- [simplemem/multimodal/orchestrator.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/multimodal/orchestrator.py)
- [simplemem/multimodal/processors/image_processor.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/multimodal/processors/image_processor.py)
- [simplemem/database/vector_store.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/database/vector_store.py)
</details>

# 核心 API、记忆管线与检索机制

## 概述与设计目标

SimpleMem 是一个面向长时记忆（long-term memory）的检索增强生成框架，v0.3.0 起将文本版 `SimpleMem`、多模态版 `Omni-SimpleMem` 以及自演化版 `EvolveMem` 统一收敛到单一 `simplemem` 包内，通过 `from simplemem import SimpleMem` 暴露入口，并由"首次调用的方法"自动决定后端路由（文本 vs 多模态）。该统一包的设计目标是：

- **语义无损压缩**：将冗长对话或文档压缩为紧凑记忆条目，降低检索时的 token 开销；
- **意图感知检索**：根据查询意图选择不同检索路径；
- **自动后端选择**：调用方无需关心底层是文本还是多模态记忆管线。

社区中关于 token 消耗的疑问（如 issue #31）以及 LoCoMo 复现差异（issue #47、#58）表明，理解**管线各阶段的 token 归属**与**检索路径**对结果复现至关重要。

## 核心 API 入口

`SimpleMem` 类对外暴露的最小可用接口围绕"写入"与"查询"两类操作：

- 写入侧：`add_text / add_conversation / add_document` 等方法触发文本记忆管线，最终由 `simplemem/core/memory_builder.py` 中的 `MemoryBuilder` 完成结构化与压缩；
- 查询侧：`search / query / ask` 等方法触发检索与回答生成，调用 `hybrid_retriever.py` 中的 `HybridRetriever`，再由 `answer_generator.py` 中的 `AnswerGenerator` 汇总生成。

由于 v0.3.0 采用"首次方法调用决定后端"的自动路由策略，调用方一旦先调用多模态方法（如处理图像），后续调用即被锁定在 `Omni-SimpleMem` 后端；反之则使用纯文本后端。这一机制在 issue #60 涉及的 `omni_memory.core.config` 缺失场景下尤为重要——多模态分支会按需加载 `OmniMemoryConfig` 等配置类（issue #49 报告该文件在某些 commit 中缺失，需从源码补齐）。

## 记忆管线（写入路径）

记忆管线负责把原始输入转换为可检索的 `MemoryEntry` 对象，核心数据模型定义在 `simplemem/core/models/memory_entry.py`。典型流程如下：

```mermaid
flowchart LR
  A[原始输入<br/>文本/对话/图像] --> B[MemoryBuilder<br/>解析与切分]
  B --> C[语义压缩<br/>Lossless Compression]
  C --> D[MemoryEntry<br/>向量化与标注]
  D --> E[(VectorStore<br/>LanceDB)]
```

- **解析与切分**：`MemoryBuilder` 负责将长文本拆分为可管理的语义单元；
- **语义压缩**：保留语义但压缩 token；该步骤是 issue #31 中"token 消耗 572"指标的主要来源；
- **结构化条目**：`MemoryEntry` 承载文本、嵌入向量、元数据（人物、实体、时间戳等），供后续检索使用；
- **持久化**：写入 `database/vector_store.py` 中的 LanceDB 表。

多模态分支由 `simplemem/multimodal/orchestrator.py` 协调，图像类输入经 `multimodal/processors/image_processor.py` 处理后注入同一记忆管线。

## 检索机制（查询路径）

检索阶段由 `HybridRetriever` 主导，结合语义向量检索与结构化过滤：

- **向量召回**：基于查询嵌入在 LanceDB 中进行近似最近邻搜索；
- **结构化过滤**：`structured_search` 方法支持按人物、实体、时间戳等条件筛选，但该方法历史上使用 f-string 直接拼接到 `.where()` 子串（issue #53），存在注入风险，调用方应避免传入不可信字段；
- **意图感知**：根据查询意图选择不同召回权重与重排策略；
- **回答生成**：`AnswerGenerator` 将召回的多条 `MemoryEntry` 汇总后送入 LLM，输出最终回答。

需特别注意的是，issue #57 报告 `langchain-openai` 旧版本存在 SSRF/DNS rebinding 漏洞，依赖清单应及时升级；issue #54 指出遗留的 `/mcp/message` 端点在缺少 bearer token 时存在未授权访问风险，部署时不应开放该端点。issue #52 则提醒 `MMLongBench-Doc` 加载器使用 `eval()` 解析数据集，**切勿加载来源不明的基准数据**。

## 常见使用模式与注意事项

| 场景 | 推荐做法 | 关联 issue |
|------|---------|-----------|
| 复现 LoCoMo / MemGallery | 确认使用统一 `simplemem` 包导入，并核对模型与提示词版本 | #47、#58、#64 |
| 控制 token 消耗 | 关注压缩后条目数与生成阶段 token，二者合计即为论文指标 | #31 |
| 多模态评测 | 检查 adapter 是否真正走图像分支而非纯文本回退 | #64 |
| 安全部署 | 升级依赖、关闭 `/mcp/message`、限制 CORS | #51、#53、#54、#57 |

## 小结

SimpleMem 的核心 API 设计遵循"单一入口、自动路由"原则；记忆管线以 `MemoryBuilder` + `MemoryEntry` 为中心，强调语义无损压缩；检索机制以 `HybridRetriever` 的混合召回 + `AnswerGenerator` 的汇总生成为闭环。在使用与部署时，应同时关注**复现一致性**（模型、提示词、token 计算口径）与**安全配置**（依赖版本、端点鉴权、CORS），以避免社区中已暴露的常见陷阱。

资料来源：[simplemem/core/memory_builder.py:1-200]()、[simplemem/core/hybrid_retriever.py:1-200]()、[simplemem/core/answer_generator.py:1-200]()、[simplemem/core/models/memory_entry.py:1-200]()、[simplemem/multimodal/orchestrator.py:1-200]()、[simplemem/database/vector_store.py:1-400]()。

---

<a id='page-3'></a>

## MCP 服务器、Docker 部署与后端集成

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [核心 API、记忆管线与检索机制](#page-2), [常见问题、复现指南、安全与社区议题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [MCP/README.md](https://github.com/aiming-lab/SimpleMem/blob/main/MCP/README.md)
- [MCP/run.py](https://github.com/aiming-lab/SimpleMem/blob/main/MCP/run.py)
- [MCP/server/http_server.py](https://github.com/aiming-lab/SimpleMem/blob/main/MCP/server/http_server.py)
- [MCP/server/mcp_handler.py](https://github.com/aiming-lab/SimpleMem/blob/main/MCP/server/mcp_handler.py)
- [MCP/server/auth/token_manager.py](https://github.com/aiming-lab/SimpleMem/blob/main/MCP/server/auth/token_manager.py)
- [MCP/server/database/vector_store.py](https://github.com/aiming-lab/SimpleMem/blob/main/MCP/server/database/vector_store.py)
</details>

# MCP 服务器、Docker 部署与后端集成

## 1. 概述与定位

SimpleMem 的 MCP（Model Context Protocol）服务器是一个独立的 HTTP 服务入口，用于把 SimpleMem 的文本/多模态记忆能力以标准协议的方式暴露给外部客户端（例如 IDE、Agent 框架、聊天机器人等）。它并不负责记忆的语义压缩与检索算法本身，而是充当"协议网关 + 鉴权层 + 后端调度器"，将客户端的写入/查询请求转发到 `simplemem` 统一包内部对应的后端（文本内存、OmniMem 多模态内存、EvolveMem 演化内存等）。`MCP/README.md` 中说明了该服务的启动方式与外部依赖配置，`MCP/run.py` 则是进程入口，负责装配配置、初始化向量库与 LLM 客户端并启动 ASGI 服务器。资料来源：[MCP/README.md]()、[MCP/run.py:1-80]()。

## 2. 系统架构

### 2.1 模块组成

服务由四个核心模块组成，职责清晰分离：

| 模块 | 路径 | 职责 |
| --- | --- | --- |
| HTTP 路由 | `MCP/server/http_server.py` | 定义 REST/MCP 端点、CORS 中间件、会话承载 |
| 协议处理 | `MCP/server/mcp_handler.py` | 解析 MCP JSON-RPC 消息，路由到具体动作 |
| 鉴权 | `MCP/server/auth/token_manager.py` | 颁发、校验 Bearer Token，关联 session_id |
| 数据层 | `MCP/server/database/vector_store.py` | LanceDB 写入、结构化检索、记忆条目持久化 |

资料来源：[MCP/server/http_server.py:1-60]()、[MCP/server/mcp_handler.py:1-60]()、[MCP/server/auth/token_manager.py:1-40]()、[MCP/server/database/vector_store.py:1-60]()。

### 2.2 请求处理流程

```mermaid
flowchart LR
  Client[客户端] -->|HTTP + Bearer Token| HTTP[http_server.py]
  HTTP -->|校验 Token| Auth[token_manager.py]
  Auth -->|建立/校验 Session| MCP[mcp_handler.py]
  MCP -->|add / search / query| VS[vector_store.py]
  VS -->|LanceDB .where() / .search()| DB[(LanceDB)]
  MCP -->|返回结构化结果| Client
```

资料来源：[MCP/server/http_server.py:40-120]()、[MCP/server/mcp_handler.py:30-100]()、[MCP/server/database/vector_store.py:60-140]()。

## 3. 鉴权与会话

`token_manager.py` 负责为每次 MCP 会话签发短期 Bearer Token，并将 Token 与内部 `session_id` 进行映射；客户端在 `Authorization` 头中携带 Token 以访问受保护端点。`mcp_handler.py` 在处理消息前会调用 Token 校验逻辑，确认会话有效后再进行动作分发。需要注意的是，社区已报告 `/mcp/message` 端点存在遗留回退路径，仅凭 `session_id` 即可绕过 Bearer 校验（issue #54，定位在第 782-786 行附近），运维方在生产部署前应禁用该回退或通过反向代理强制鉴权。资料来源：[MCP/server/auth/token_manager.py:20-90]()、[issue #54]()。

## 4. Docker 部署

`MCP/README.md` 与 `MCP/run.py` 描述了两种典型部署形态：

- **本地开发**：直接通过 `python MCP/run.py` 启动 Uvicorn，监听 `127.0.0.1`；
- **容器化部署**：基于项目根目录的 `Dockerfile` 构建镜像，把 `MCP` 目录作为服务工作目录，使用环境变量注入 `OPENAI_API_KEY`、`LANCEDB_URI`、`MCP_TOKEN_SECRET` 等敏感配置；容器对外暴露 8000 端口，建议通过 Nginx/Caddy 反向代理并启用 HTTPS。

启动时 `run.py` 会调用 `http_server.py` 创建 FastAPI 应用，注册 `/healthz`、`/mcp/message`、`/v1/memories` 等路由，并装配 CORS 中间件。社区 issue #51 指出默认 CORS 配置使用 `allow_origins=["*"]` 与 `allow_credentials=True` 的组合存在跨域凭据窃取风险，生产部署应改为显式白名单。资料来源：[MCP/README.md]()、[MCP/run.py:40-120]()、[issue #51]()。

## 5. 后端集成

MCP 服务器并不直接实现 SimpleMem 的语义压缩、意图感知检索或多模态融合逻辑，而是作为"薄壳"调用 v0.3.0 统一包 `simplemem.SimpleMem`。`mcp_handler.py` 接收到 `add_text` / `add_multimodal` / `search` 等动作后，会根据当前后端配置（文本 / OmniMem / EvolveMem）转发到对应入口；检索阶段最终都会落到 `vector_store.py` 的 `structured_search` 与 `semantic_search`，前者基于 `persons`、`entities`、`timestamp` 等元数据构造 LanceDB `.where()` 过滤（社区 issue #53 指出此处存在 SQL/过滤注入风险，应改为参数化查询）。因此在使用 MCP 部署时，建议同步升级到最新版本并启用参数化过滤。资料来源：[MCP/server/mcp_handler.py:80-160]()、[MCP/server/database/vector_store.py:100-200]()、[issue #53]()。

---

<a id='page-4'></a>

## 常见问题、复现指南、安全与社区议题

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [核心 API、记忆管线与检索机制](#page-2), [MCP 服务器、Docker 部署与后端集成](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [OmniSimpleMem/benchmarks/memgallery/](https://github.com/aiming-lab/SimpleMem/tree/main/OmniSimpleMem/benchmarks/memgallery)
- [OmniSimpleMem/omni_memory/core/config.py](https://github.com/aiming-lab/SimpleMem/blob/main/OmniSimpleMem/omni_memory/core/config.py)
- [database/vector_store.py](https://github.com/aiming-lab/SimpleMem/blob/main/database/vector_store.py)
- [OmniSimpleMem/benchmarks/mm_longbench_doc/loader.py](https://github.com/aiming-lab/SimpleMem/blob/main/OmniSimpleMem/benchmarks/mm_longbench_doc/loader.py)
- [OmniSimpleMem/mcp_server/http_server.py](https://github.com/aiming-lab/SimpleMem/blob/main/OmniSimpleMem/mcp_server/http_server.py)
- [test_locomo10.py](https://github.com/aiming-lab/SimpleMem/blob/main/test_locomo10.py)
- [test_ref/load_dataset.py](https://github.com/aiming-lab/SimpleMem/blob/main/test_ref/load_dataset.py)
- [test_ref/test_advanced.py](https://github.com/aiming-lab/SimpleMem/blob/main/test_ref/test_advanced.py)
- [test_ref/utils.py](https://github.com/aiming-lab/SimpleMem/blob/main/test_ref/utils.py)
- [EvolveMem/run_benchmark.py](https://github.com/aiming-lab/SimpleMem/blob/main/EvolveMem/run_benchmark.py)
- [EvolveMem/run_evolution.py](https://github.com/aiming-lab/SimpleMem/blob/main/EvolveMem/run_evolution.py)
- [simplemem/__init__.py](https://github.com/aiming-lab/SimpleMem/blob/main/simplemem/__init__.py)
</details>

# 常见问题、复现指南、安全与社区议题

## 概述

本页面向希望复现论文结果、调试环境问题或评估 SimpleMem 安全态势的开发者与研究者，集中整理来自 GitHub Issues 与源码中的高频问题、复现步骤、已报告的漏洞以及社区合作意向。SimpleMem 当前处于 v0.3.0 阶段，文本版（SimpleMem）、多模态版（Omni-SimpleMem）与自演化版（EvolveMem）已合并为统一的 `simplemem` 包，通过首次调用方法自动路由至文本或多模态后端。

资料来源：[simplemem/__init__.py:1-40]()

## 复现指南

### LoCoMo 基准复现

LoCoMo 是社区关注度最高的复现目标。建议按以下步骤操作：

1. 准备数据：使用 `test_ref/load_dataset.py` 加载 LoCoMo 数据集并切分对话/问答对。资料来源：[test_ref/load_dataset.py:1-80]()
2. 配置后端：`test_locomo10.py` 默认使用 GPT-4o，但官方论文使用的是不同 checkpoint，因此复现时分数可能存在 ±4 的偏差。资料来源：[test_locomo10.py:1-60]()
3. 跑评测：`test_ref/test_advanced.py` 提供了带意图感知检索的完整评估脚本。资料来源：[test_ref/test_advanced.py:1-120]()

社区报告（Issue #58）显示，基于仓库代码使用 GPT-4o 复现 LoCoMo 通常会得到约 44.6 的分数，而论文报告为 39.06。这一偏差主要源于论文使用的是不同模型快照与评测脚本。复现小型 Qwen 模型（Qwen2.5-1.5B/3B、Qwen3-1.7B/8B）时，分数差异主要来自温度、prompt 模板与检索 top-k 设置（Issue #47）。

### EvolveMem 与 MemGallery

EvolveMem 的复现入口位于 `EvolveMem/run_evolution.py` 与 `EvolveMem/run_benchmark.py`，分别执行记忆条目演化与基准评测。资料来源：[EvolveMem/run_evolution.py:1-100]()、资料来源：[EvolveMem/run_benchmark.py:1-120]()

MemGallery 是一个多模态基准，但当前 `OmniSimpleMem/benchmarks/memgallery/` 下的适配器仅使用了文本信息，**未实际调用原图进行评估**（Issue #64）。如需完整多模态复现，需要自行扩展该适配器以注入图像特征。

## 常见问题

### 配置模块缺失

OmniSimpleMem 中多个文件通过 `from omni_memory.core.config import OmniMemoryConfig` 引入配置，但 `omni_memory/core/` 目录下没有 `config.py`，导致导入失败（Issue #49、#60）。临时解决方法是从 `simplemem` 统一包导入配置类，或使用 v0.3.0 之后的版本。资料来源：[OmniSimpleMem/omni_memory/core/config.py:1-1]()

### Token 消耗口径

论文中报告的 token 数（例如 LoCoMo + Qwen2.5-3B 上的 572）指的是**总消耗**，包含记忆生成阶段与问答检索阶段的全部调用（Issue #31）。`test_ref/utils.py` 提供了按阶段切分的统计工具。资料来源：[test_ref/utils.py:1-80]()

### 与其他记忆系统对比

社区常将 SimpleMem 与 Beads / Claude-mem 进行对比（Issue #7）。SimpleMem 强调语义无损压缩与意图感知检索，定位偏向研究型记忆框架，而非任务看板类工具。

## 安全议题

下表汇总已披露的安全问题及其影响范围：

| Issue | 位置 | 风险类型 | 影响 |
| --- | --- | --- | --- |
| #51 | MCP HTTP 服务 CORS 配置 | `allow_origins=["*"]` + `allow_credentials=True` | 跨源凭据窃取 |
| #52 | MMLongBench-Doc loader 使用 `eval()` | 基准数据篡改可触发任意代码执行 | 远程代码执行 |
| #53 | `VectorStore.structured_search` 使用 f-string 拼接过滤条件 | 用户提供的 person/entity 名称未转义 | SQL/过滤注入 |
| #54 | 旧版 `/mcp/message` 仅以 `session_id` 鉴权 | 攻击者可猜测/获取有效会话 | 未授权会话访问 |
| #57 | `langchain-openai` 旧版本 + DNS rebinding | SSRF 保护可绕过 | 服务端请求伪造 |

资料来源：[OmniSimpleMem/mcp_server/http_server.py:782-786]()、资料来源：[OmniSimpleMem/benchmarks/mm_longbench_doc/loader.py:1-60]()、资料来源：[database/vector_store.py:1-200]()、资料来源：[OmniSimpleMem/mcp_server/http_server.py:1-100]()

对于 Issue #51 与 #54，建议将 CORS 白名单收敛为可信域名，并为 MCP 端点强制要求 Bearer Token。Issue #52 的 `eval()` 应替换为 `ast.literal_eval()`。Issue #53 的过滤条件应使用参数化查询或白名单校验。

## 社区议题与集成建议

社区目前讨论的集成与合作关系主要集中在两个方向：

1. **压缩层叠加**：LLM RAG Booster（Issue #62）提议将基于"引力编码"的零依赖压缩层接入 SimpleMem 的记忆管线，目标是在保证 100% 完整性的前提下获得约 8.1× 的 token 压缩。该方案可作为 `MemoryBuilder` 的可选前置阶段。
2. **黑客松与社区共办**：GeekRoom / Own 1（Issue #63）提议联合举办美欧区域虚拟黑客松，由合作方提供算力与奖品。

此外，SimpleMem v0.3.0 的发布说明强调"一次导入、自动路由"，用户在切换文本与多模态记忆时无需修改调用代码。资料来源：[simplemem/__init__.py:1-40]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：aiming-lab/SimpleMem

摘要：发现 19 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：How can I reproduce the locomo results on GPT-4o。

## 1. 安全/权限坑 · 来源证据：How can I reproduce the locomo results on GPT-4o

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How can I reproduce the locomo results on GPT-4o
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/58 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Question about the evaluation protocol used for MemGallery

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Question about the evaluation protocol used for MemGallery
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/64 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：Sponsored partnership

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Sponsored partnership
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/63 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/aiming-lab/SimpleMem | host_targets=mcp_host, claude, cursor, chatgpt

## 5. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/aiming-lab/SimpleMem | README/documentation is current enough for a first validation pass.

## 6. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/aiming-lab/SimpleMem | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/aiming-lab/SimpleMem | no_demo; severity=medium

## 8. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/aiming-lab/SimpleMem | no_demo; severity=medium

## 9. 安全/权限坑 · 来源证据：Missing OmniSimpleMem package config module: omni_memory.core.config

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Missing OmniSimpleMem package config module: omni_memory.core.config
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/60 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 安全/权限坑 · 来源证据：Request for more evaluation details for Table 3 on LoCoMo

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Request for more evaluation details for Table 3 on LoCoMo
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/47 | 来源类型 github_issue 暴露的待验证使用条件。

## 11. 安全/权限坑 · 来源证据：Security: Hardcoded default JWT secret and encryption key in MCP server

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: Hardcoded default JWT secret and encryption key in MCP server
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/50 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 12. 安全/权限坑 · 来源证据：Security: Legacy /mcp/message endpoint allows unauthenticated session access via session_id

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: Legacy /mcp/message endpoint allows unauthenticated session access via session_id
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/54 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 13. 安全/权限坑 · 来源证据：Security: Overly permissive CORS allows cross-origin credential theft

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: Overly permissive CORS allows cross-origin credential theft
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/51 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 14. 安全/权限坑 · 来源证据：Security: SQL/filter injection in VectorStore.structured_search via unsanitized person/entity names

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: SQL/filter injection in VectorStore.structured_search via unsanitized person/entity names
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/53 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 15. 安全/权限坑 · 来源证据：Security: eval() used on benchmark data allows code injection

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: eval() used on benchmark data allows code injection
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/52 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 16. 安全/权限坑 · 来源证据：Vulnerability in SimpleMem project

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Vulnerability in SimpleMem project
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/57 | 来源类型 github_issue 暴露的待验证使用条件。

## 17. 安全/权限坑 · 来源证据：[Integration Proposal] LLM RAG Booster — Gravitational Compression to reduce SimpleMem token footprint

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Integration Proposal] LLM RAG Booster — Gravitational Compression to reduce SimpleMem token footprint
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/aiming-lab/SimpleMem/issues/62 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 18. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/aiming-lab/SimpleMem | issue_or_pr_quality=unknown

## 19. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/aiming-lab/SimpleMem | release_recency=unknown

<!-- canonical_name: aiming-lab/SimpleMem; human_manual_source: deepwiki_human_wiki -->