一句话定位:AI 与人共用的长期记忆底座。用 项目 → 分组 → 条目 三级树组织全部知识,以 纯 HTTP API 对内外同时开放——Agent 用它记住昨天,人用它读写同一份记忆。
概念概况:一个 Flask 单体服务、一个 SQLite 库文件、一套三级 REST 接口、一个 Markdown 网页端——生态内任意 Agent 一个 Token 即接入,人与 AI 永远读写同一批记忆,可检索、可分享、可导出、可随整库文件迁移。
MemKV 不是为演示而生。它来自 Leon 全栈生态的真实运转——当几十个 Agent 会话并行开跑,偏好、SOP、设备密码、排障经验 必须像人一样被「记住」,而不是每次重讲一遍。
全部服务端逻辑收在一个 Flask 单体里:1828 行 app.py + 14 个 API 蓝图 + 259 行数据模型。没有消息队列、没有缓存集群、没有向量服务——克制换来的是十年如一日的稳定与随手可备份。
POST /item/add,三级寻址后落库,带时间戳与标签。GET /search,按名称 / 摘要 / 内容 / 标签四字段模糊命中。references 逐条 item/content,拼出完整上下文进 prompt。md / json / html / pdf,或生成公开链接与二维码。MemKV 的全部关键逻辑都能在一屏里读完。以下四个片段取自生产源码(192.168.11.70 · LZ-Memory 仓库),未改一字,仅作排版节选:先看数据如何站住(模型),再看记忆如何被想起(检索),最后看它如何被安全地改与删(更新语义、公网删除)。
class Item(db.Model):
__tablename__ = 'item'
id = db.Column(db.Integer, primary_key=True, autoincrement=True)
group_id = db.Column(db.Integer, db.ForeignKey('group.id'), nullable=False)
name = db.Column(db.String(100), nullable=False)
summary = db.Column(db.Text, default='')
md_content = db.Column(db.Text, default='')
tags = db.Column(db.Text, default='')
references = db.Column(db.Text, default='')
seo_settings = db.Column(db.Text, default='') # JSON 字符串,per-item SEO 覆盖,空串=无覆盖
create_time = db.Column(db.DateTime, default=datetime.utcnow)
update_time = db.Column(db.DateTime, onupdate=datetime.utcnow)
hidden = db.Column(db.Boolean, default=False)
attachments = db.relationship('Attachment', backref='item',
cascade='all, delete-orphan', lazy='dynamic')
shares = db.relationship('Share', backref='item',
cascade='all, delete-orphan', lazy='dynamic')
__table_args__ = (
db.UniqueConstraint('group_id', 'name', name='uq_group_item_name'),
)
一条记忆 = 摘要 + 正文 + 标签 + 引用四件套。references 以文本列存引用清单,是「递归补全上下文」的种子;group_id + name 唯一约束保证同分组不重名——后来 Unicode 字元撞名的坑(见 06 段)正是被这条约束「拦下来才被发现」。回收站复用 tags 内嵌 __recycled__ 标记位,SEO 覆盖存 JSON 字符串列:扩展能力全部走列内编码,表结构一次定型。
@api_bp.route('/search', methods=['GET'])
def search():
"""全文搜索:在条目名称、摘要、内容、标签中搜索关键词"""
keyword = request.args.get('keyword', '').strip()
project_name = request.args.get('project_name', '').strip()
tag = request.args.get('tag', '').strip()
if not keyword and not tag:
return api_response(code=1, msg='请提供 keyword 或 tag 参数')
query = Item.query.join(Group).join(Project)
if project_name:
query = query.filter(Project.name == project_name)
if keyword:
pattern = f'%{keyword}%'
query = query.filter(
db.or_(
Item.name.like(pattern),
Item.summary.like(pattern),
Item.md_content.like(pattern),
Item.tags.like(pattern)
)
)
if tag:
query = query.filter(Item.tags.like(f'%{tag}%'))
items = query.order_by(Item.update_time.desc()).all()
# 逐条组装 project/group/item 三元组 + summary/tags/references/update_time 回传
return api_response(data=results)
没有 Embedding、没有向量索引——四字段 LIKE + 摘要排序就是全部检索。这正是 05 段选型的落点:中小规模(< 1 万条)下召回足够准,命中理由可解释、冷启动为零、单机成本为零;实测「记忆」一词 234 条命中约 70ms 返回。
@api_bp.route('/item/update', methods=['PUT'])
def item_update():
data = request.get_json() or {}
# project_name / group_name / item_name 三级寻址;条目不存在则 code=3 返回
...
if new_item_name and new_item_name != item_name:
existing = Item.query.filter_by(group_id=group.id, name=new_item_name).first()
if existing:
return api_response(code=2, msg=f'条目 "{new_item_name}" 已存在')
item.name = new_item_name
if summary is not None:
item.summary = summary
if md_content is not None:
item.md_content = md_content
if tags is not None:
item.tags = tags
if references is not None:
item.references = references
# SEO:用 'seo_settings' in data 区分“未传键=不改”与“传 null/{}=清空”
if 'seo_settings' in data:
seo_raw = data.get('seo_settings')
item.seo_settings = _serialize_seo(seo_raw) if seo_raw else ''
db.session.commit()
return api_response(msg='条目更新成功', data=item.to_dict())
PUT 是字段级部分更新:传什么字段改什么字段,None 与「键不传」被严格区分。但正因为 md_content 本身就是一个字段——传片段 = 整段替换,一次险些丢光全文的实测事故(见 06 段①)由此而来,也由此定下「先 GET 全文、本地改完、PUT 完整回写」的操作纪律。区分「没传」与「传空」的在场判断('key' in data),是这套语义里最值得抄的一行。
@api_bp.route('/item/erase', methods=['POST'])
def item_delete_external():
"""外部设备友好的条目删除端点(POST 透传 DELETE 业务逻辑)
用途:公网入口的 nginx/WAF 拦截 URL 中含 'delete' 字样的请求(含 DELETE 方法
和任何方法的 /api/v1/*/delete 路径),外部设备无法直接调用 DELETE 端点。
本端点用 POST + 路径 /item/erase(避开 delete 关键字)实现,业务与
DELETE /api/v1/item/delete 完全等价,便于跨公网调用。
"""
data = request.get_json() or {}
project_name = (data.get('project_name') or '').strip()
group_name = (data.get('group_name') or '').strip()
item_name = (data.get('item_name') or '').strip()
if not project_name or not group_name or not item_name:
return api_response(code=1, msg='项目名称、分组名称和条目名称不能为空')
project, group, item = get_item_or_none(project_name, group_name, item_name)
if not item:
return api_response(code=3, msg=f'条目 "{item_name}" 不存在')
db.session.delete(item)
db.session.commit()
return api_response(msg=f'条目 "{item_name}" 已删除')
这段 docstring 本身就是设计文档:公网路径上的 WAF 会拦截任何含 delete 字样的 URL,连 DELETE 方法一并封死。于是同一份业务逻辑再开一扇门——POST /item/erase,名字里不带那个词。接口设计不只是定义功能,还要绕开链路上每一台会替你做主的设备。
四段真实的选型与设计过程——每个决定都经历过需求 → 候选对比 → 权衡 → 落地的完整回路,结论都写进了接口与文档,而不是靠记性。
Agent 要能讲清「为什么命中」;冷启动不能依赖任何模型与 GPU;生态规模在中小量级(数百至 < 1 万条目)。
传统向量方案给不了可解释性——黑盒相似度对排障毫无帮助。
向量库:语义召回好,但要 Embedding 服务、冷启动慢、$50+/月 起步。
纯关键词:零依赖、可解释,短板是同义表达——靠摘要字段与 references 递归补齐语境。
定案 关键词 + 摘要 + References 三件套:四字段 LIKE 召回,摘要当语义锚点,引用递归补上下文。
预留演进口:未来可挂可选向量层,现有纯关键词路径始终独立可用。
多 Agent 并发写不能互相覆盖,要事务;备份要「一个文件拷走」;部署目标是零外部服务。
文档层面一度把数据格式记成「JSON 文件」——与真实实现对不上,说明书本身也会踩坑。
JSON 散文件:直观,但无事务、并发写互踩、全树靠扫描。
PostgreSQL:能力过剩,得常驻一个数据库服务,违背零依赖初衷。
SQLite:文件型、带事务、无需安装任何数据库服务。
定案 Flask-SQLAlchemy + SQLite,单文件 memory.db 即整库;README 写明「开箱即用」。
留好迁路:写并发或体量上来换 PostgreSQL,ORM 只改连接串、API 一字不动。今天已同步修正 wiki 与架构页的数据格式表述。
外部设备走公网删条目总是失败:链路上的 nginx / WAF 拦截一切含 delete 字样的 URL,连 DELETE 方法本身也被封。
业务逻辑完全正常,死在了「词」上。
改网关白名单:要动安全设备规则,影响面大、审批重。
换业务名再开端点:不动链路、不动安全策略,只是把同一逻辑再开一扇门。
定案 POST /item/erase:路径避开敏感词,docstring 写明与 DELETE 端点完全等价。
约定:外部设备只用 erase,管理员内网仍用 DELETE——跨公网删除脚本自此跑通。
调用方经常只改 tags 或 summary,不该被迫重传整条正文;「没传的键」与「传了空值」必须区别对待(清空 vs 不动)。
全量覆盖式 PUT:客户端易漏字段,一次误传丢一片。
字段级部分更新:省流量、语义清晰;代价是「字段值本身可能就是一整篇正文」,客户端仍会犯错。
定案字段级语义:None 判断管改不改,'key' in data 在场判断管清不清。
同时立操作纪律:正文修改一律 GET 全文 → 本地改 → PUT 整段回写,并在接入指南里写死——语义只解决接口,纪律才防住人。
五个真实难点,全部来自生产环境实测——它们没有一个会在编译期暴露,全部长在「跨设备、跨平台、跨公网」的真实链路上。
PUT /item/update 只传 {"md_content": "片段"},本以为是追加——实际 md_content 是一个字段,传什么就是新的完整值,整条正文被整段替换,几乎全文丢失。
解决:改文前先 GET 拿完整内容,本地改完回写完整正文;本地镜像 + 历史版本做兜底(本次正是靠它救回)。该纪律已写入记忆库操作规范。
GET /item/content → 本地修改 → PUT /item/update(md_content = 完整正文)
# 永远不要只传片段
U+5FC6 与 U+5FF8。手打错一个:查询返回「条目不存在」像极了云端掉数据;写入则生成与原条仅差一个码点的 duplicate,唯一约束也拦不住(名字真的不一样)。
解决:名称一律 Python 构造 + 码点校验,写前查 memory/index 确认唯一,发现错字元版本用 erase 擦除。
NAME = "记" + chr(0x5FC6) + "系统-Agent"
[hex(ord(c)) for c in NAME] → 第2字必须是 '0x5fc6'
400 乱码;响应头里藏 UTF-8 BOM → json.loads 当场炸;Windows 上 curl 是别名、&&; 语法不认;工具 WebFetch 强制 http→https,连不上纯 http 服务。
解决:四条约束全部写进接入指南,形成跨平台清单。
curl -G --data-urlencode "keyword=开发" http://119.145.17.34:5001/api/v1/search
json.loads(raw.encode().decode('utf-8-sig')) # 先脱 BOM
Windows: curl.exe + 分号分隔 # 别用 curl 别名、别用 &&
取数用 Python / curl.exe,Never WebFetch
GET /memory/index 体积大、满屏 \u3010 转义,命令行一滚就截断——结构明明拿到了,却没法读。
解决:解码用 utf-8-sig + ensure_ascii=False 重排后阅读;先 /search 定位、再读单条;给人留了免认证的 /readme 只读树入口。
json.dumps(json.loads(raw), ensure_ascii=False, indent=1) # 转义还原成人读的字
# 先 search 定位 → 再 item/content 读全文,别整树硬吞
wswwsw1234 手敲易错,敲错只得到一个「像是坏了」的空结果。
解决:一切以实测为准,遇疑当面验证;凭据写成变量复用;访问默认携带认证。
TOKEN=wswwsw1234
curl -H "Authorization: Bearer $TOKEN" http://119.145.17.34:5001/api/v1/memory/index
# 文档陷阱可能过时,当面验证后再下结论