01
独立服务
以本地 HTTP 服务形式运行，对外提供写入、提取、搜索、上下文构建、更新、遗忘与导出接口。
01 / PRODUCT POSITION
系统定位与设计边界
该系统不是聊天机器人，也不是简单的向量数据库，而是运行在应用与模型之间的本地记忆中间层。
02
模型解耦
LLM 与 Embedding Provider 均采用适配器模式，可替换 Ollama、本地推理框架或 OpenAI 兼容接口。
03
记忆可控
用户可以查看系统记住了什么、为什么保存、来自哪里，并可修改、停用、删除或彻底清空。
04
结构化优先
事实状态保存在关系数据库；向量索引仅用于召回候选，不作为事实真伪和冲突裁决依据。
05
多作用域
支持全局、应用、项目、会话四级作用域，避免某个项目中的临时偏好污染其他场景。
06
渐进实现
第一阶段优先完成可靠写入、搜索和上下文构建；复杂知识图谱、多租户和云同步后置。
系统负责
- 接收消息、事件与外部结构化事实
- 识别值得长期保存的信息
- 生成结构化记忆与向量索引
- 执行混合检索、重排和上下文压缩
- 处理重复、更新、冲突、过期和遗忘
- 提供审计、导出、备份和恢复能力
系统不负责
- 聊天 UI 与完整对话产品体验
- 主模型答案生成和工具调用编排
- 模型训练、微调和参数更新
- 云端账号体系和复杂多租户权限
- 第一版中的复杂知识图谱推理
- 替代业务系统自身的主数据管理
02 / ARCHITECTURE
总体架构
采用“调用方应用 → 记忆服务 → 持久化与模型 Provider”的三层结构，核心业务逻辑与具体模型、向量库实现隔离。
本地聊天应用
发送用户消息，获取相关记忆上下文。
AI Agent / RPA
写入任务事件、决策和执行状态。
其他业务系统
通过 HTTP 或 SDK 复用统一记忆能力。
→
API Gateway
鉴权、参数校验、请求 ID、限流、错误规范。
Memory Orchestrator
编排提取、去重、冲突分析、写入和异步任务。
Retrieval & Context Builder
混合召回、重排、Token 预算和上下文输出。
Lifecycle Manager
版本替代、自动过期、归档、遗忘与审计。
→
SQLite
事实、状态、版本、来源与审计记录。
ChromaDB
语义向量索引，仅负责候选召回。
LLM Provider
提取、冲突分析、压缩与语义判断。
Embedding Provider
为记忆和查询生成统一向量。
建议服务地址：
http://127.0.0.1:8765；默认只监听本机回环地址。03 / CORE MODULES
核心模块设计
模块之间通过明确的数据契约协作，任何模型输出都必须经过 Schema 校验，不能直接写入主存储。
IN
Ingestion
接收消息、事件、任务状态和业务事实；完成来源标识、幂等键与作用域绑定。
EX
Extraction
调用本地模型判断是否值得保存，并提取类型、主体、关系、内容、置信度与有效期。
CO
Consolidation
执行规范化、去重、兼容性判断、更新和冲突分析，避免记忆无限重复增长。
RE
Retrieval
综合语义、关键词、作用域、类型、置信度、重要性与时效进行混合召回和重排。
CX
Context Builder
按 Token 预算整理少量高相关记忆，生成外部模型可直接注入的简洁上下文。
LF
Lifecycle
管理版本历史、停用、自动过期、归档、用户显式遗忘、批量删除和彻底清空。
1接收输入
消息、应用 ID、项目 ID、会话 ID、元数据与幂等键。
2候选提取
严格 JSON 输出，拒绝模型自由文本直接入库。
3规范化
统一实体名、类型、作用域、时间与字段格式。
4合并判断
重复、兼容、更新、冲突、无关五类关系。
5持久化
事务写入 SQLite，并提交异步向量索引任务。
6可用记忆
进入检索、上下文构建、版本审计与生命周期管理。
04 / DATA MODEL
记忆模型与存储设计
SQLite 是事实源，ChromaDB 是派生索引。任何向量数据都可以通过 SQLite 全量重建。
| 字段 | 类型 | 用途 | 关键约束 |
|---|---|---|---|
id | UUID | 记忆唯一标识 | 主键，不复用 |
memory_type | Enum | profile / preference / project / task / decision / event / fact / instruction | 必须受控枚举 |
scope | Enum | global / application / project / conversation | 决定检索隔离范围 |
content | Text | 供展示、检索和上下文构建的标准描述 | 不得包含不可解析的模型原始输出 |
subject / predicate / object | Text | 结构化语义关系 | 允许部分为空，但事实类优先完整 |
importance | Float | 长期价值评分 | 0.0～1.0 |
confidence | Float | 信息确定程度 | 0.0～1.0；推测不得高置信 |
expires_at | DateTime? | 临时记忆自动过期时间 | 长期偏好可为空 |
is_active | Boolean | 当前是否参与检索 | 旧版本和删除记录必须停用 |
superseded_by | UUID? | 指向替代当前记忆的新版本 | 保留完整演进链路 |
source_* | Text | 应用、会话、消息、项目来源 | 每条自动记忆必须可追溯 |
metadata_json | JSON | 扩展业务标签、实体和提取信息 | Schema 版本化 |
Memory DTOJSON
{
"memory_type": "preference",
"scope": "global",
"subject": "user",
"predicate": "prefers_response_language",
"object": "zh-CN",
"content": "用户偏好使用中文回答。",
"importance": 0.86,
"confidence": 0.99,
"expires_at": null
}
建议附加表
- memory_versions：保存修改前后的完整快照。
- memory_sources：一条记忆可对应多个支持来源。
- retrieval_logs：记录每次候选、评分和最终注入结果。
- conflict_logs：记录冲突关系、裁决依据和处理结果。
- jobs：管理提取、向量化、重建索引与过期扫描任务。
- settings：保存应用级和全局记忆策略。
05 / RETRIEVAL
混合检索与上下文构建
向量相似度只负责发现“可能相关”，最终排序必须结合业务作用域、时效和结构化属性。
final_score =
semantic_similarity × 0.35
+ keyword_match × 0.15
+ scope_match × 0.20
+ type_match × 0.10
+ importance × 0.08
+ confidence × 0.07
+ recency × 0.05
默认权重
语义相关度35%
关键词匹配15%
作用域匹配20%
类型匹配10%
重要性8%
置信度7%
时间相关性5%
检索流程
- 先根据应用、项目、会话作用域过滤不可见记忆。
- 从 ChromaDB 召回语义候选，同时执行 SQLite 关键词召回。
- 合并候选并排除过期、停用、被替代和低置信记录。
- 按综合评分重排，默认保留 5～12 条。
- 记录候选、评分、过滤原因和最终结果，便于调试。
上下文构建原则
- 按“用户偏好、项目事实、近期状态、历史事件”分区。
- 优先输出确定事实，不输出内部 ID、向量和数据库字段。
- 设置最大 Token 预算，超出后按相关性和重要性裁剪。
- 显式注明记忆可能过期或存在不确定性。
- 当前用户明确表达与旧记忆冲突时，以当前表达优先。
06 / API CONTRACT
核心 API 设计
接口采用版本化 REST API；写入接口支持幂等键，搜索与上下文接口返回可解释的评分和来源。
| 方法 | 路径 | 用途 | 关键返回 |
|---|---|---|---|
| POST | /api/v1/ingest | 接收一轮消息或业务事件 | 任务 ID、处理状态 |
| POST | /api/v1/memories/extract | 同步提取候选记忆，适合调试 | 候选列表、保存建议 |
| POST | /api/v1/memories | 手动创建结构化记忆 | 记忆详情 |
| GET | /api/v1/memories | 分页查询和筛选记忆 | 列表、分页信息 |
| PATCH | /api/v1/memories/{id} | 修改内容、类型、作用域或有效状态 | 新版本详情 |
| DELETE | /api/v1/memories/{id} | 软删除单条记忆 | 删除结果、审计记录 |
| POST | /api/v1/memories/search | 返回结构化检索结果 | 候选、评分、来源 |
| POST | /api/v1/context/build | 生成可直接注入模型的上下文 | context、memories、Token 估算 |
| POST | /api/v1/forget | 按自然语言或条件查找待删除范围 | 预览、确认令牌 |
| POST | /api/v1/reindex | 从 SQLite 重建向量索引 | 任务状态、进度 |
| GET | /api/v1/health | 检查数据库、模型和向量服务 | 组件状态 |
POST /api/v1/context/buildRequest
{
"user_id": "frank",
"application_id": "local-chat",
"project_id": "memory-system",
"query": "继续上次的开发",
"max_tokens": 800,
"limit": 8
}
Context ResponseJSON
{
"context": "【用户偏好】...\n【当前项目】...",
"token_estimate": 436,
"memories": [
{
"id": "...",
"score": 0.91,
"reason": "project_scope + semantic_match"
}
]
}
07 / CONSISTENCY
冲突、更新与遗忘
系统不直接覆盖旧事实，而是保存版本链和裁决证据，使任何变化都可回溯。
=
Duplicate
语义一致且作用域相同。合并来源、增加支持次数，不重复新增有效记录。
+
Compatible
新旧信息可以共存，例如全局使用 Java、某个项目使用 Python。
↻
Update
新信息是旧信息的更新。旧记录停用，新记录启用，并建立 superseded_by 关系。
!
Contradiction
语义方向相反。根据当前明确表达、作用域、来源、置信度和时间进行裁决。
∅
Unrelated
仅文本相似但事实无关，不参与合并或冲突处理。
×
Forgetting
删除前先预览匹配范围；默认软删除和索引移除，彻底清空需要二次确认。
关键规则
用户本轮明确表达 > 项目级最新事实 > 全局稳定偏好 > 模型推断。任何低置信推测都不能覆盖用户明确陈述。
08 / PRIVACY & SECURITY
隐私与安全设计
默认本地优先、最小权限和最小暴露。即使未来接入云端模型，也必须由用户显式开启。
L
仅监听本机
默认绑定 127.0.0.1，不开放局域网；远程访问必须显式配置鉴权和 TLS。
P
隐私模式
支持关闭长期记忆、仅保存原始记录、不保存当前会话、禁止指定类型写入。
S
敏感信息策略
默认不自动保存密码、密钥、令牌、证件号码和高敏感个人信息。
A
完整审计
记录创建、修改、停用、删除、冲突裁决与批量操作，不记录不必要的完整敏感正文。
B
备份恢复
SQLite 与向量索引分开备份；向量索引损坏时可以根据主数据库无损重建。
E
可选加密
第二阶段支持数据库文件加密、备份加密和本地密钥管理，不把密钥硬编码到项目中。
09 / TECHNOLOGY STACK
技术栈与工程结构
第一版优先选择本地部署简单、社区成熟、便于测试和迭代的组件。
推荐技术栈
- API：Python 3.12 + FastAPI
- 配置：Pydantic Settings
- 数据库：SQLite + SQLAlchemy + Alembic
- 向量索引：ChromaDB
- 本地模型：Ollama Provider
- Embedding：bge-m3 或其他可替换模型
- 任务：应用内持久化任务队列，后续可替换 Redis
- 测试：Pytest + HTTPX
- 包管理：uv
- 接口文档：OpenAPI / Swagger
Project StructureTEXT
local-memory-service/ ├─ app/ │ ├─ api/ │ ├─ core/ │ ├─ models/ │ ├─ schemas/ │ ├─ repositories/ │ ├─ services/ │ │ ├─ ingestion/ │ │ ├─ extraction/ │ │ ├─ consolidation/ │ │ ├─ retrieval/ │ │ ├─ context/ │ │ └─ lifecycle/ │ └─ providers/ │ ├─ llm/ │ └─ embedding/ ├─ migrations/ ├─ data/ │ ├─ sqlite/ │ └─ chroma/ ├─ sdk/ │ ├─ python/ │ └─ typescript/ ├─ tests/ ├─ scripts/ ├─ .env.example ├─ start.bat └─ README.md
10 / DELIVERY ROADMAP
分阶段实施路线
每阶段都应形成可独立运行、可验收、可提交 Git 的版本，不一次性堆叠全部复杂能力。
Phase 0
服务骨架与数据契约
完成 FastAPI、配置、SQLite、Alembic、健康检查、统一错误、OpenAPI 和基础测试。
交付：可启动的本地服务与稳定 API 基础。
Phase 1
手动记忆 CRUD
实现记忆模型、版本记录、筛选查询、软删除和基础审计。
交付：不依赖 LLM 的可靠记忆数据库。
Phase 2
自动提取与写入
接入本地 LLM Provider，严格 JSON Schema 提取，增加去重、幂等和异步任务。
交付：从消息自动形成结构化记忆。
Phase 3
向量索引与混合检索
接入 Embedding、ChromaDB、关键词搜索、作用域过滤、综合评分和降级策略。
交付：稳定且可解释的相关记忆搜索。
Phase 4
上下文构建
实现 Token 预算、分区输出、去冗余、来源引用和检索调试信息。
交付：外部模型可直接注入的 context。
Phase 5
冲突、更新与遗忘
完成重复、兼容、更新、冲突关系；加入自动过期、批量遗忘和版本链。
交付：可长期运行的记忆一致性机制。
Phase 6
SDK、备份与运维
提供 Python/TypeScript SDK、Windows 脚本、导入导出、备份恢复和性能指标。
交付：可被多个本地项目稳定复用的基础设施。
11 / ACCEPTANCE
MVP 验收标准
MVP 的价值不在功能数量，而在于记忆可追溯、检索相关、冲突可处理、数据可控制。
✓
独立运行
Windows 本地一键启动，服务不依赖聊天 UI 和具体主模型。
✓
稳定写入
可手动或自动保存结构化记忆，每条记录包含来源、作用域和置信度。
✓
相关检索
新会话可以找回相关偏好和项目事实，无关记忆不会大量注入。
✓
故障降级
Embedding 或向量库不可用时自动降级为关键词检索，不阻断调用方。
✓
一致性
新旧事实冲突时可以停用旧版本、启用新版本，并保留完整演进记录。
✓
用户控制
支持查看、编辑、删除、导出、备份、恢复和清空全部本地记忆。
12 / RISK MANAGEMENT
关键风险与缓解措施
记忆系统的主要风险不是“存不下来”，而是错误记忆、过期记忆、污染检索和不可控删除。
高
模型提取错误
所有输出强制 Schema 校验；低置信候选不自动入库；明确区分用户陈述和模型推断。
高
旧记忆污染回答
加入作用域隔离、过期时间、版本替代和当前表达优先规则。
高
向量相似但语义相反
向量只用于召回；最终冲突必须结合谓词、否定词、时间和 LLM 语义判断。
中
SQLite 与向量索引不一致
SQLite 作为唯一事实源；索引写入采用任务表和重试；提供全量重建能力。
中
上下文过长
强制 Token 预算、候选上限、相似记忆合并和结构化压缩。
中
误删除或过度遗忘
删除前预览范围；默认软删除；批量与全量删除必须二次确认并写入审计。
最终结论
该方案将“记忆”建设为独立本地基础设施：主模型可以更换、聊天前端可以重做、Agent 可以增加，但长期记忆的数据模型、检索逻辑、冲突规则与用户控制能力无需重复开发。