01 / 计划书PROJECT BRIEF

MemKV 记忆库

一句话定位:AI 与人共用的长期记忆底座。用 项目 → 分组 → 条目 三级树组织全部知识,以 纯 HTTP API 对内外同时开放——Agent 用它记住昨天,人用它读写同一份记忆。

概念概况:一个 Flask 单体服务、一个 SQLite 库文件、一套三级 REST 接口、一个 Markdown 网页端——生态内任意 Agent 一个 Token 即接入,人与 AI 永远读写同一批记忆,可检索、可分享、可导出、可随整库文件迁移。

516条
记忆条目 · 实时
6项目 / 48分组
三级树规模
5.6MB
单文件库 memory.db
≈70ms
检索响应 · 实测
RECENT MEMORIES Skill / opencode 多节点编排 偏好 / 每日简报时间与格式 设备 / TK-Server 部署路径 排障 / WAF 拦截 delete 关键字 SOP / 静态站三段式部署链路 MEMORY GROWTH · SCHEMATIC
02项目来源 · Origin

一个朴素的问题:谁来替 Agent 记住昨天?

MemKV 不是为演示而生。它来自 Leon 全栈生态的真实运转——当几十个 Agent 会话并行开跑,偏好、SOP、设备密码、排障经验 必须像人一样被「记住」,而不是每次重讲一遍。

🔍立项时的背景与痛点

2026 年上半年 · 生态扩张期
  • 多 Agent、多设备并行:opencode 多节点编排、Leon-Control、各业务平台同时在跑,同一份知识要在几十个会话间流动。
  • 新会话即失忆:每次开聊都要重新解释背景(「金鱼脑」),换一台设备还得手抄上下文。
  • 知识散落各处:Skill 文档、排障记录、设备配置散在本地文档与聊天记录里,Agent 调用前到处拼凑。
  • 外部方案不合身:Notion / Confluence 回吐 HTML 海洋,解析贵、按人头收费;向量库要 Embedding 冷启动,黑盒相似度说不清「为什么命中」。

🎯立项要解决什么

四条硬性目标 · 至今未变
  • AI-First 输出:纯 JSON / Markdown 直接拼进 prompt,零预处理、零 HTML 噪音。
  • 人机对称:同一批记忆,人用网页读写批注,AI 用 API 读写——两边永远看的是同一份。
  • 零成本单机:不要向量模型、不要外部数据库服务,一个 Python 进程 + 一个库文件跑起来。
  • 可解释召回:关键词 + 摘要 + References 三件套,命中理由能向人讲清楚。
方案 A · BEFORE
🗂️传统知识库
  • Notion / Confluence 返回渲染后的 HTML,Agent 先剥皮去骨才能用
  • 无结构时间戳,更新难追溯
  • 按人头订阅,$8 / 人 / 月起
方案 B · BEFORE
🔮向量数据库
  • 需 Embedding 模型,冷启动慢、依赖 GPU
  • 黑盒相似度,命中无法解释
  • Pinecone / Milvus 月费 $50+ 起步
方案 C · 选定
🧠MemKV
  • 纯 JSON 直拼 prompt,LLM 友好
  • 关键词 + References 可解释、可调试
  • 单机 ¥0,SQLite 开箱即用
2026 年 3—6 月 · 内部服务形态先行
作为生态共享记忆服务开始运转
2026-08 的展示页已记载「稳定运行 5+ 个月」——先有服务,后有仓库。
2026-06-30
源码首次入 Git 仓库(LZ-Memory)
完整服务端代码 + Skill 文档落库,此后按版本演进。
2026-08-26
官网展示站上线(Leon-Web-Host 托管)
随【项目】汇总批量建站进入 leyon 体系,对外有了门面。
2026-09-15
AI Agent 接入指南并入记忆库条目
触发场景、标准流程、Skills 目录合为一处,成为全生态 Agent 的统一入口。
2026-10-21
接入四入口 / 说明书体系,展示页按六段新规范重制
项目卡收敛为 展示 / 说明书 / 架构 / 日志 四入口,本页即六段重制版首作。
03技术栈与架构图示 · Stack & Architecture

刻意克制的技术栈:一层 API、一个库文件、零外部依赖

全部服务端逻辑收在一个 Flask 单体里:1828 行 app.py + 14 个 API 蓝图 + 259 行数据模型。没有消息队列、没有缓存集群、没有向量服务——克制换来的是十年如一日的稳定与随手可备份。

🐍Python 3服务端语言 🌶️FlaskWeb 框架 · app.py 🧩Blueprint ×14api/ 模块化路由 🗄️Flask-SQLAlchemyORM 数据层 📀SQLitememory.db 单文件 📝markdown2MD 渲染预览 🔀Mermaid + Node图表预渲染 SVG 🧾WeasyPrintPDF 导出 📄python-docxDOCX 导出 🎨cairosvg矢量图形处理 🔷qrcode分享二维码 🔐Bearer Token接口鉴权 ⚙️systemd常驻托管 · 自动拉起
🤖 AI Agent opencode · Skills · 各项目后端 🌐 Web 编辑器 人 · Markdown 读写 / 分享 / 导出 📱 外部设备 curl / PowerShell · 公网接入 REST · JSON · Bearer Token MemKV HTTP API :5001 app.py · Flask · api/ 蓝图 ×14 · Bearer 鉴权 search / item / group / project / share / export / visibility / docs … ② 召回 JSON → prompt ① 写入落库 附件 / 图表渲染 多格式导出 📀 SQLite · memory.db SQLAlchemy ORM · 5.6 MB 单文件 项目 → 分组 → 条目 三级表结构 🗂️ 附件与渲染 attachments/ · mermaid_render/ 图片附件 · Mermaid Node 预渲染 📦 导出引擎 MD · JSON · HTML · PDF WeasyPrint · python-docx · qrcode ONE PROCESS · ONE DB FILE · ZERO EXTERNAL SERVICES
图:模块组合与数据流动——三类客户端经同一 HTTP 入口读写,存储与渲染全部收敛在单进程内
FLOW 01
写入
Agent 或人提交 POST /item/add,三级寻址后落库,带时间戳与标签。
FLOW 02
会话启动召回
新会话先 GET /search,按名称 / 摘要 / 内容 / 标签四字段模糊命中。
FLOW 03
递归补全
沿 references 逐条 item/content,拼出完整上下文进 prompt。
FLOW 04
归档分享
按需导出 md / json / html / pdf,或生成公开链接与二维码。
04核心代码展示 · Core Code

核心代码展示:结构、检索、更新、删除——四段真实源码

MemKV 的全部关键逻辑都能在一屏里读完。以下四个片段取自生产源码(192.168.11.70 · LZ-Memory 仓库),未改一字,仅作排版节选:先看数据如何站住(模型),再看记忆如何被想起(检索),最后看它如何被安全地改与删(更新语义、公网删除)。

models.py · L92 — class Item结构地基
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/search_api.py · L7 — def search()检索的心脏
@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/item_api.py · L136 — def item_update()字段级更新语义
@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/item_api.py · L200 — def item_delete_external()公网删除 · erase
@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,名字里不带那个词。接口设计不只是定义功能,还要绕开链路上每一台会替你做主的设备。

05踩坑分析与方案形成 · How the Design Took Shape

不是先有框架再填坑,是坑把方案逼成了现在的样子

四段真实的选型与设计过程——每个决定都经历过需求 → 候选对比 → 权衡 → 落地的完整回路,结论都写进了接口与文档,而不是靠记性。

P1检索方案:向量 RAG,还是关键词三件套?
踩坑 · 需求

Agent 要能讲清「为什么命中」;冷启动不能依赖任何模型与 GPU;生态规模在中小量级(数百至 < 1 万条目)。

传统向量方案给不了可解释性——黑盒相似度对排障毫无帮助。

对比 · 权衡

向量库:语义召回好,但要 Embedding 服务、冷启动慢、$50+/月 起步。

纯关键词:零依赖、可解释,短板是同义表达——靠摘要字段与 references 递归补齐语境。

形成 · 方案

定案 关键词 + 摘要 + References 三件套:四字段 LIKE 召回,摘要当语义锚点,引用递归补上下文。

预留演进口:未来可挂可选向量层,现有纯关键词路径始终独立可用。

P2存储方案:JSON 散文件、SQLite,还是 PostgreSQL?
踩坑 · 需求

多 Agent 并发写不能互相覆盖,要事务;备份要「一个文件拷走」;部署目标是零外部服务。

文档层面一度把数据格式记成「JSON 文件」——与真实实现对不上,说明书本身也会踩坑。

对比 · 权衡

JSON 散文件:直观,但无事务、并发写互踩、全树靠扫描。

PostgreSQL:能力过剩,得常驻一个数据库服务,违背零依赖初衷。

SQLite:文件型、带事务、无需安装任何数据库服务。

形成 · 方案

定案 Flask-SQLAlchemy + SQLite,单文件 memory.db 即整库;README 写明「开箱即用」。

留好迁路:写并发或体量上来换 PostgreSQL,ORM 只改连接串、API 一字不动。今天已同步修正 wiki 与架构页的数据格式表述。

P3删除接口:正经 DELETE,过不了公网这道关
踩坑 · 现象

外部设备走公网删条目总是失败:链路上的 nginx / WAF 拦截一切含 delete 字样的 URL,连 DELETE 方法本身也被封。

业务逻辑完全正常,死在了「词」上。

对比 · 权衡

改网关白名单:要动安全设备规则,影响面大、审批重。

换业务名再开端点:不动链路、不动安全策略,只是把同一逻辑再开一扇门。

形成 · 方案

定案 POST /item/erase:路径避开敏感词,docstring 写明与 DELETE 端点完全等价。

约定:外部设备只用 erase,管理员内网仍用 DELETE——跨公网删除脚本自此跑通。

P4更新语义:Agent 只想改一个标签,怎么办?
踩坑 · 需求

调用方经常只改 tags 或 summary,不该被迫重传整条正文;「没传的键」与「传了空值」必须区别对待(清空 vs 不动)。

对比 · 权衡

全量覆盖式 PUT:客户端易漏字段,一次误传丢一片。

字段级部分更新:省流量、语义清晰;代价是「字段值本身可能就是一整篇正文」,客户端仍会犯错。

形成 · 方案

定案字段级语义:None 判断管改不改,'key' in data 在场判断管清不清。

同时立操作纪律:正文修改一律 GET 全文 → 本地改 → PUT 整段回写,并在接入指南里写死——语义只解决接口,纪律才防住人。

06技术难点与解决法 · Hard Problems & Fixes

技术难点与解决法:上线之后,链路教会我们的事

五个真实难点,全部来自生产环境实测——它们没有一个会在编译期暴露,全部长在「跨设备、跨平台、跨公网」的真实链路上。

难点 ① · 高危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'
难点 ③跨平台接入「四连坑」:中文、BOM、PowerShell、WebFetch
解决法
现象:中文直接拼 URL → 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
难点 ④整棵记忆树直出:\u 转义海 + 终端截断
解决法
现象: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 读全文,别整树硬吞
难点 ⑤文档与实测打架:写在纸上的约束,未必还成立
解决法
现象:文档写「GET 带 Content-Type 必 400」,实测 200;文档写「index 无需认证」,实测不带 Token 返回空树;凭据 wswwsw1234 手敲易错,敲错只得到一个「像是坏了」的空结果。 解决:一切以实测为准,遇疑当面验证;凭据写成变量复用;访问默认携带认证。 TOKEN=wswwsw1234 curl -H "Authorization: Bearer $TOKEN" http://119.145.17.34:5001/api/v1/memory/index # 文档陷阱可能过时,当面验证后再下结论
共同规律把约束写进接口与文档,而不是靠记性
收束
这五个难点的共性:编译期全都看不见——字元表、编码、代理、网关、文档时效,全是运行世界才有的变量。MemKV 的应对自成一套方法论:接口层开 erase 端点绕 WAF、字段级语义保数据;工具层码点校验、脱 BOM、变量复用;文档层踩坑即更新、以实测覆写文字。约束被固化成流程之后,「下一次别再踩」才第一次变得可靠。
📖 说明书📐 说明文档🕘 日志