个人记忆服务

这是一个面向单用户助手的本地记忆服务 旨在让记忆可随处引用

服务通过本地 HTTP/OpenAPI 对外提供接口，底层使用 SQLite 持久化记忆数据，使用 sqlite-vec 做向量检索，使用 FTS5 做全文检索与回退召回。

目标定位

• 面向单个用户
• 本机部署、本机服务调用
• 以长期记忆为核心
• 优先接入云端大模型
• 只暴露本地 HTTP/OpenAPI 接口

支持的记忆范围

领域

• work：工作
• personal：个人
• family：家庭

记忆类型

• fact：事实
• preference：偏好
• event：事件
• task：任务 / 计划 / 待办

当前整体工作流

写入流程

1. 外部服务调用 POST /agent/memorize
2. 服务接收对话消息
3. 记忆提取器将消息提取成候选记忆
4. 过滤敏感信息和疑似乱码
5. 从现有记忆中检索相关内容
6. 记忆决策器判断应当：
   • insert
   • upsert
   • update
   • merge
   • skip
7. 将最终结果写入 SQLite
8. 同步全文索引和向量索引
9. 写入审计日志，记录提取、跳过、更新、合并、召回等行为

检索流程

1. 外部服务调用 POST /agent/recall
2. 服务根据查询语句做向量召回 + 关键词召回
3. 融合以下因素打分排序：
   • 向量相似度
   • 关键词命中
   • 主领域优先
   • 重要度
   • 新近性
   • 置信度
4. 返回最终候选记忆列表

智能策略

一、模型优先

当以下配置存在时：

API_KEY=...
BASE_URL=...
MODEL=...

系统会优先使用大模型完成：

• 记忆提取
• 冲突判断
• 插入 / 合并 / 更新 / 跳过 决策

二、本地规则回退

如果模型调用失败，或者模型没有提取出任何候选记忆，系统会自动回退到本地启发式规则。

当前已增强的中文规则包括：

• 家庭安排
• 个人健康计划
• 工作任务清单
• 中文时间表达识别
• 中文任务计划识别

三、向量能力

向量配置单独管理：

EMBEDDING_API_KEY=
EMBEDDING_BASE_URL=
EMBEDDING_MODEL=
EMBEDDING_DIMENSIONS=1536

它们的作用分别是：

• EMBEDDING_API_KEY：向量模型调用密钥
• EMBEDDING_BASE_URL：向量模型接口地址
• EMBEDDING_MODEL：向量模型名称
• EMBEDDING_DIMENSIONS：向量维度

如果未配置 EMBEDDING_MODEL，系统会自动回退到本地哈希向量。

这意味着你现在即使没有单独的 embedding 模型，系统也可以正常工作，只是向量质量会低于真实 embedding 模型。

配置说明

在项目根目录创建 .env，示例：

API_KEY=sk-...
BASE_URL=
MODEL=gpt-5.3-codex

EMBEDDING_API_KEY=
EMBEDDING_BASE_URL=
EMBEDDING_MODEL=
EMBEDDING_DIMENSIONS=1536

SQLITE_DB_PATH=data/memory.db
APP_HOST=127.0.0.1
APP_PORT=8765

同时也兼容以下别名：

• OPENAI_API_KEY
• OPENAI_BASE_URL
• OPENAI_MEMORY_MODEL
• OPENAI_EMBEDDING_API_KEY
• OPENAI_EMBEDDING_BASE_URL
• OPENAI_EMBEDDING_MODEL

安装

pip install -e .

启动

uvicorn app.main:app --host 127.0.0.1 --port 8765

启动后可访问：

• Swagger 文档：http://127.0.0.1:8765/docs
• OpenAPI JSON：http://127.0.0.1:8765/openapi.json
• 健康检查：http://127.0.0.1:8765/health

核心接口

• POST /memories
• POST /memories/upsert
• POST /memories/search
• POST /memories/consolidate
• GET /memories
• GET /memories/audit/recent
• GET /memories/{memory_id}
• PATCH /memories/{memory_id}
• DELETE /memories/{memory_id}
• POST /memories/merge
• POST /agent/memorize
• POST /agent/recall

记忆写入示例

import httpx

payload = {
    "preferred_domain": "family",
    "auto_commit": True,
    "conversation": [
        {
            "role": "user",
            "content": "这周六上午十点带孩子去口腔复查，结束后顺路买学习用品。"
        }
    ],
}

resp = httpx.post("http://127.0.0.1:8765/agent/memorize", json=payload, timeout=60.0)
print(resp.json())

记忆检索示例

import httpx

payload = {
    "query": "回顾这周六孩子口腔复查的安排",
    "primary_domain": "family",
    "allow_cross_domain": True,
    "top_k": 5,
}

resp = httpx.post("http://127.0.0.1:8765/agent/recall", json=payload, timeout=60.0)
print(resp.json())

清洗示例

import httpx

payload = {
    "dry_run": False,
    "delete_sensitive": True,
    "delete_garbled": True,
    "dedupe_exact": True,
    "resolve_entity_conflicts": True,
}

resp = httpx.post("http://127.0.0.1:8765/memories/consolidate", json=payload, timeout=60.0)
print(resp.json())

当前已经实现的能力

• SQLite + sqlite-vec + FTS5
• work / personal / family 三大领域
• fact / preference / event / task 四类记忆
• OpenAI 兼容 responses 风格模型调用
• 模型优先的记忆提取
• 模型优先的记忆决策
• 提取为空时自动回退本地规则
• 稳定偏好/事实的 upsert
• 重复记忆跳过
• 敏感信息过滤
• 乱码内容过滤
• 合并/更新/删除/归档/覆盖
• 审计日志
• 本地回归测试脚本

最近新增和修正

• 修正了中文内容被误判为乱码的问题
• 加强了中文任务和计划类提取
• 增加了提取阶段审计日志
• 增加了跳过原因审计日志
• 增加了乱码判定信号输出
• 新增回归测试脚本 simulate_memory_flow.py

本地验证结果

在 2026-03-27 已完成以下验证：

• 服务成功启动
• /health 正常
• /agent/memorize 正常
• /agent/recall 正常
• /memories/audit/recent 正常
• 中文家庭安排记忆可写入
• 中文个人健康计划可写入
• 工作记忆可补充并 merge
• 敏感信息不会写入
• 测试数据可自动清理

测试日志文件：

• memory_flow_test_log_20260326.md
• memory_flow_test_log_20260326_round2.md
• memory_flow_test_log_20260327_230545_round3.md

当前已知问题

• 模型在带有“测试标记”这类输入时，偶尔会多抽取一条噪声事件记忆
• 历史数据里仍存在部分 entity_key 命名不统一的问题，例如：
  • user.preference.language
  • response_language
• 如果后续接入真实 embedding 模型，召回质量还有进一步提升空间

建议的下一步

1. 统一历史 entity_key
2. 为真实使用场景构建一小批评测样本
3. 给低置信度事件记忆增加 TTL / 复核机制
4. 给测试标记类输入增加更严格的降噪策略