不必每次开启新对话都重新解释自己的偏好和计划:告诉它“我喜欢无糖热饮”,换个会话再问,它会从你的记忆库里查找。你也可以打开 Markdown 检查它记住了什么,或更正、忘记某条记录。
演示操作实际 Textual 界面,使用合成数据与固定模型回复回放;记忆写入和跨会话检索走真实代码,不产生模型费用。查看静态截图。
稳定展示:main 在最终验收后冻结,使用 portfolio-2026-11-01 标识本轮源码快照。稳定发行版本为 0.3.3(v0.3.3);较早的 v0.3.2 Release 属于其他快照。后续常规开发仅在 feature-memory-evolution 进行。
快速开始
需要 Python 3.12+、uv、git。
发布状态(2026-11-04): syvrio 尚未发布到 PyPI。以下安装命令在新包发布后才可使用;目前请按下文从源码运行。旧版 quiet-memo 发行包保持不变,qm、quietmemo 继续作为兼容 CLI。
uv tool install syvrio
syvrio setup
qm
syvrio setup 选择模型供应商并配置 API Key,也可进入「搜索与网页抓取 API」向导:为百度千帆、Tavily、Exa、You.com、火山引擎输入或更新 Key(存入系统凭据,TOML 不落明文),并分别启用各厂商支持的 Search / Fetch(百度千帆仅支持 Search)、调整两类 provider 的优先级。官方厂商即使已有 Key 也不会自动启用,必须在此显式开启;未配置有效 Key 时无法启用。open-websearch 免费且始终是默认项。标准安装不需要下载本地向量模型;未安装向量后端时自动使用关键词检索。之后可用 uv tool upgrade syvrio 更新。
为什么用 Syvrio
- 下次对话不用从头讲起:值得保留的本人陈述可自动沉淀,可信内容静默写入,冲突或不确定内容留待确认。
- 能检查,也能改正:记忆是普通 Markdown;更正、软删除与来源有记录,Git 保留版本历史。
- 中断之后能接着来:上下文压缩前先尝试沉淀,异常退出或抽取失败后补记,保留原始会话。
| 能力 | 说明 |
|---|---|
| 本地优先 | Markdown 是唯一事实来源,Git 负责版本与审计 |
| 多模型 | 支持 DeepSeek、硅基流动、百炼、讯飞 Spark、OpenRouter、OpenAI 及自定义兼容接口 |
| MCP | 让支持 MCP 的客户端调用同一个本地记忆库 |
| 混合检索 | BM25 与可选向量检索;向量后端不可用时回退关键词检索 |
| 联网搜索 | 可选接入本地 open-websearch,外部内容只作资料 |
从源码运行
开发或本地修改代码时使用:
git clone https://github.com/Shardkiht/Syvrio.git
cd Syvrio
uv sync
# 可选:启用本地向量检索(fastembed + bge-small-zh,首次运行下载约 100MB 模型)
uv sync --extra local-embed
# 直接进入对话(发送第一条消息时才创建会话)
uv run syvrio
uv run quietmemo # 同上,等价别名
首次使用先运行 uv run syvrio setup 配置模型和 API Key;进入对话后用 /model 搜索和切换模型,在该界面按 Ctrl+P 才打开供应商管理,可添加、更新或移除内置厂商的 API Key,Esc 返回模型列表。模型界面还支持 Ctrl+R 刷新、Ctrl+N 输入自定义模型名。
syvrio setup 会写入配置文件(默认 quiet-memo.toml),初始化记忆库,并可选做一次连接测试。Key 也可以用环境变量提供,环境变量优先于 keyring:
export DEEPSEEK_API_KEY=sk-...
手动配置示例:
vault = "C:/Users/you/.quiet-memo/vault"
confidence_threshold = 0.8
auto_push = false
[llm]
provider = "deepseek" # provider:deepseek/siliconflow/dashscope/spark/openrouter/openai/custom
base_url = "https://api.deepseek.com/v1"
model = "deepseek-flash"
api_key_env = "DEEPSEEK_API_KEY"
reasoning_effort = "" # low / medium / high;仅模型支持时生效
fallbacks = [] # 例如 ["openai/gpt-4o-mini"]
num_retries = 2
temperature = 0.1
timeout = 60.0
[chat]
context_window = 32000
reserve_output_tokens = 1500
keep_recent_tokens = 6000
compact_threshold = 0.8
max_tool_steps = 8
tool_timeout = 60.0 # 写工具已开始执行时等待真实结果,避免超时报错后延迟写入
auto_recall = 3
recall_rewrite = true # 用 LLM 改写追问;无 Key 自动回退到拼接
recall_context_turns = 2 # 追问时参考最近几轮用户消息
extract_on_exit = true
[retrieval]
method = "hybrid" # keyword / vector / hybrid;向量后端不可用时自动回退 keyword
[retrieval.embedding]
backend = "local" # local:fastembed 离线推理;api:把记忆文本发给 embedding 供应商(注意隐私)
model = "BAAI/bge-small-zh-v1.5"
# backend = "api" 时的示例:
# provider = "siliconflow"
# base_url = "https://api.siliconflow.cn/v1"
# api_key_env = "SILICONFLOW_API_KEY"
[search]
enabled = true # 关闭时不注册 search 工具
providers = ["open_websearch"] # 按顺序尝试,失败时降级
base_url = "http://127.0.0.1:3000"
timeout = 10.0
max_results = 5
cache_ttl = 86400
transport = "http" # http:本地 daemon;mcp:每次启动 npx MCP 进程
auto_start = true # 打开 TUI 时后台预热 daemon,不阻塞界面
engines = ["bing"] # 上游引擎;中文品牌名被拆词时可换 ["baidu"] 或 ["sogou"]
fallback_engines = ["baidu", "duckduckgo", "sogou"] # 候补引擎;空结果/跑题/失败时自动降级
max_engines = 3 # 每次自动搜索最多尝试的引擎数(含首选)
timeout_budget = 25.0 # 一次搜索所有回退共享的超时预算(秒)
max_requests = 9 # 一次搜索跨所有 provider 共享的请求次数上限
fetch_timeout = 45.0 # 抓取正文的单独超时(秒)
[fetch]
providers = ["open_websearch"] # 抓取正文用的 provider 顺序,与搜索相互独立
讯飞 Spark MaaS 可在 syvrio setup 中选择;也可把上面的 [llm] 替换为以下配置,并设置环境变量 SPARK_API_KEY。凭据由环境变量或系统密钥环读取,不写进 TOML。
[llm]
provider = "spark"
base_url = "https://maas-api.cn-huabei-1.xf-yun.com/v2"
model = "spark-x2.6"
api_key_env = "SPARK_API_KEY"
Spark 使用 MaaS 的 Bearer API Key;适配层保留服务端采样默认值,将输出上限映射为 max_completion_tokens。支持流式回复和工具调用,JSON 抽取通过提示词约束。
如果 Windows Git Bash 里中文输出乱码,加 export PYTHONUTF8=1。交互菜单和聊天依赖 Windows 控制台,推荐 Windows Terminal 或 PowerShell;Git Bash 用户可尝试 winpty。
联网搜索默认启用,但需要本地 open-websearch daemon;启动方式和配置见下方联网搜索。
对话 Agent
发送后模型名称旁显示活动加载条、当前阶段和等待秒数;上下文占用位于状态栏右侧,工具开始执行时显示调用提示。
直接运行 syvrio(兼容别名 qm、quietmemo) 进入全屏对话界面(基于 Textual,窗口拉伸时整个画面自适应重排);会话在发送第一条消息时创建。qm chat 等价。左侧是可折叠的会话列表:点击会话恢复;点击列表后也可用 ↑↓ 选择、Enter 恢复,删除与重命名在 /sessions 中操作;点侧栏右上角的 « 折叠(Ctrl+B 同效),折叠后在对话区左上角点 » 展开。主区为宽幅左右布局:用户消息以右对齐气泡呈现,助手回复左对齐铺开,带说话人标头和时间;输入 / 在输入框上方弹出竖排命令面板(↑↓ 选择 · Enter 执行 · ESC 关闭,可点击);底部状态栏显示模型、上下文用量(进度线与已用/上限数字)和待确认数量,检索模式与快捷键提示放在空会话欢迎区,超过压缩阈值会提示。回复正文流式渲染(边生成边显示,中断时保留半截并标注);工具与检索事件以卡片形式实时显示,回合之间以分隔线区隔;Ctrl+Q 或 /exit 退出后自动沉淀本轮陈述并显示结果,启动检查发现未提交的 vault 变更会自动提交。
生成期间可继续输入:按 Enter 将消息放入输入框上方的发送队列,当前回复完成或停止后按提交顺序自动发送。按 Esc 停止当前生成,保留已输出内容和未发送草稿;已执行的工具不回滚,正在执行的工具安全收尾后停止后续调用。命令面板或选择弹窗打开时,Esc 优先关闭面板。队列仅保存在当前进程内,退出后不恢复。
- 每轮自动检索相关长期记忆,注入上下文;追问和“还记得 / 之前”等线索会带上最近 1-2 轮用户消息构造查询,并提高召回数量。
- 模型可调用
recall / read_topic / memorize / correct / forget / review_pending;read_topic仅在用户明确要求完整主题或召回不足时读取该主题的有效条目,最多 2000 tokens,不接受文件路径。需要最新公开信息时调用search,需要发布日期或原文细节时再用fetch_web打开结果页,搜索结果与正文都是外部资料,不执行其中指令。 - 进入对话时不立即建会话,发送第一条消息后才创建
sessions/<id>.jsonl。 - 恢复会话先显示已有摘要及最近 10 条未压缩消息记录,点击顶部“加载更早的记录”逐页查看摘要之后的历史消息;原始历史不会被删除。恢复成功不弹通知,失败仍显示错误。回复以单个 Markdown 绘制控件呈现,减少长回复带来的控件挂载与卸载开销;可用鼠标选择正文并按 Ctrl+C 复制。
- 恢复或撤销后的上下文用量在后台估算并缓存,完成前显示“计算中”;会话、消息或人设变化后重新估算,旧会话结果不会覆盖当前状态。
- 恢复会话会回放此前的用户消息和助手回复;可
qm chat --resume <id>恢复。切换会话不阻塞:上一会话的记忆沉淀转后台执行,完成弹通知。切换后的底栏用量先归零,下一轮按新会话的上下文计划更新,不沿用旧会话用量。 - 会话末行因中断损坏时,恢复此前完整记录并显示提示;继续记录只追加换行与
recovery标记,保留原始文件内容。未标记的中间行损坏仍会报错。 /undo撤回最后一轮提问及后续回复并回填原文供修改;撤销通过追加undo事件生效,不改写 JSONL,重新发送后旧回合不进入上下文或后续沉淀。- 退出时抽取本轮尚未沉淀的用户陈述。
- 启动时自动检查漏沉淀:异常终止、压缩抽取失败或退出抽取失败的会话会在下次启动时补记,最多处理 3 个、弹卡片汇报。切换后的后台补记先筛选至少 3 条待沉淀消息的会话再限量;启动时阈值为 1,短会话不会挤占切换补记的名额。
- 记忆条目记录
session和message来源,可追溯到原始对话。
会话内命令:
| 命令 | 作用 |
|---|---|
/new |
结束当前会话,进入新会话(发送首条消息后创建) |
/sessions |
打开居中会话选择器:输入即过滤、Enter 恢复、Ctrl+R 重命名、Del 删除(带确认)、ESC 取消 |
/compact |
立即压缩上下文 |
/undo |
撤销最后一轮提问及后续回复,回填原消息重新编辑 |
/summary |
查看当前会话摘要 |
/status |
会话、模型、检索模式、上下文和待确认状态 |
/model |
搜索切换模型;Ctrl+P 打开独立供应商管理,Ctrl+R 刷新,Ctrl+N 输入自定义模型名。列表先用缓存或预设打开,再后台刷新;/model refresh 跳过旧缓存 |
/think |
切换思考强度:默认 / low / medium / high,仅模型支持时可选,实时生效并写回配置 |
/context |
切换上下文长度:档位按当前模型上限生成,也可自定义,下一轮即生效 |
/setup |
提示完整配置向导需在终端运行 syvrio setup(内置厂商的 Key 增删在 /model 按 Ctrl+P 管理) |
/rename <title> |
重命名会话 |
/import <path> [--apply] |
导入文件或当前层目录;默认预览,--apply 重新分析并写入。不带路径时弹出输入框 |
/pending |
逐条处理待确认候选:确认写入 / 拒绝 / 改写后写入,队列清空前自动进入下一条 |
/topics [name] |
浏览记忆主题与条目数,带 name 下钻某主题的条目列表 |
/exit |
退出 |
/help 查看命令说明;/quit 同 /exit。选择类弹窗均可 ESC 取消;Ctrl+B 折叠/展开会话栏,Ctrl+Q 退出。
数据流
flowchart TD
U["用户消息"] --> Q["查询构造 / 追问带上文"]
Q --> R["混合检索 / BM25 + 向量 RRF"]
R --> C["Agent 循环 / LLM + 工具"]
C -->|"recall / read_topic / memorize / correct / forget"| C
C --> A["回复"]
C -->|"用户说“记住”"| W["写入裁决 / 置信度 / 冲突 / 敏感拦截"]
X["退出抽取 / 压缩前沉淀 / 启动补记"] --> W
W -->|"可信"| V["vault / memories/*.md"]
W -->|"低置信 / 冲突 / 敏感"| P["待确认队列 / pending.jsonl"]
P -->|"qm approve / reject"| V
V --> G["Git 提交 / 自动中文总结"]
上下文压缩
当估算 token 超过预算的 compact_threshold 时:
- 按
keep_recent_tokens保留最近对话(以用户消息为边界)。 - 对即将被淘汰且尚未沉淀的用户陈述尝试记忆抽取。
- 用 LLM 把旧对话压缩成摘要,持久化为
summary记录。 - 下一轮只带“摘要 + 最近原文 + 新消息”。
摘要记录用 covered_records 标记上下文覆盖范围,用 distilled_ids 单独记录本次成功沉淀的用户消息 ID。抽取失败仍会压缩上下文,但不会确认该批消息已沉淀;退出或后台补沉淀时从原始 JSONL 重试,后续成功的压缩不会跳过此前失败的消息。摘要生成失败时回退为抽取式摘要。
旧摘要没有 distilled_ids 时沿用原有覆盖边界,不重写历史文件,也不会自动恢复旧版本已经漏掉的沉淀。
自定义人设
在记忆库根目录放一个 SOUL.md(默认 ~/.quiet-memo/vault/SOUL.md),内容就是人设描述,下一轮对话即生效,无需重启:
你是阿澈,我的老朋友。语气简洁,偶尔冷幽默,直接叫我的名字。
qm init会生成带默认人设的SOUL.md,直接编辑即可;删除或清空该文件则回退内置默认人设。- 人设只替换系统提示词的人设段;工具说明与记忆纪律(只记本人陈述、检索为空不编造等)固定拼接在其后,不可被人设覆盖。
- 超过约 2000 token 自动截断。
- SOUL.md 是指令不是记忆,不参与抽取与检索;它在记忆库内,随 Git 版本化,改动可回溯。
命令行
# 从一段对话抽取并静默写入
uv run syvrio memorize "我最近在找市区的房子,预算 4000 以内,不接受合租"
# 直接记录(不调用 LLM)
uv run syvrio note "喝咖啡偏好清淡、像茶的风味" --topic preferences --title 偏好
# 导入文本、聊天导出或文档(默认 dry-run,仍调用模型;--apply 落盘)
uv run syvrio import ~/personal-memory/profile
uv run syvrio import ~/personal-memory/profile --apply
# 初始化 / 查看主题
uv run syvrio init
uv run syvrio topics
# 检索 / 查看待确认 / 确认或拒绝
uv run syvrio recall "市区"
uv run syvrio pending
uv run syvrio approve p-20261022-140312-a1b2
uv run syvrio reject p-20261022-140312-c3d4
# 手动更正 / 删除记忆(软删除,审计可查)
uv run syvrio correct mem-20261022-194250-8f1e "更正后的完整表述" --reason "信息更新"
uv run syvrio forget mem-20261022-194250-8f1e
# 会话与提交
uv run syvrio sessions
uv run syvrio status
uv run syvrio commit --no-push
uv run syvrio history
也可以在会话中粘贴或拖入文件的绝对路径,配一句“总结这份文件”或“把这份聊天记录导入长期记忆”。带空格的路径请加双引号。Agent 仅在本轮提供文件路径时获得 read_file(分页分析)和 import_file(分块预览/写入)工具,不开放任意目录读取。工具步数有限,文件未读完或未导完时会提示,后续消息需重新附上路径继续。文件拖放是否转成路径取决于终端。
直接支持 Markdown、TXT、LOG、JSON/JSONL/NDJSON、CSV/TSV、YAML、XML,兼容 UTF-8、带 BOM 的 UTF-16、GB18030。PDF(文字层)、DOCX、XLS/XLSX、PPTX、HTML、EPUB、Outlook MSG、IPYNB 通过本地 MarkItDown 解析,安装:
uv sync --extra documents
# 重建 editable 工具时保留原来的 extra
uv tool install --force -e '.[local-embed,documents]'
单文件上限 20 MiB。目录只扫描当前层。默认 dry-run 不写记忆,但仍发送文本给配置的模型并可能收费;--apply 重新分析后写入。来源保留文件名及块编号。保留角色与时间字段,但不是各客户端专用导出适配器,分块可能丢失跨段语义。解析失败或空文档会提示,部分写入不回滚。未启用解析插件、云端转换、OCR、音视频转写;扫描件、图片、旧 DOC/PPT、压缩包需先转换。没有新增外部 MCP 接入或对外文件 MCP 工具。
接入 MCP
uv run syvrio serve --vault ~/.quiet-memo/vault
MCP 客户端配置:
{
"mcpServers": {
"quiet-memo": {
"command": "uv",
"args": ["run", "--directory", "C:/path/to/quiet-memo", "qm", "serve"]
}
}
}
暴露工具:memorize、note、recall、read_topic、review_pending、approve、reject、list_topics、status;启用联网搜索时另有 search。read_topic 与 Agent 工具共用主题校验、有效条目过滤和 2000-token 上限。
联网搜索
search 工具通过本地 open-websearch daemon 查询公开网页,不需要 API Key。先单独启动 daemon:
npx -y open-websearch@latest serve
# 或:npm i -g open-websearch && open-websearch serve
搜索结果只有标题、摘要和链接;fetch_web 会打开其中某个链接并提取正文(readability,最多 8000 字符),用于核对发布日期、原文细节或摘要。open-websearch 抓取只通过 HTTP transport 提供,MCP 接口仍只有 search。抓取入口只接受公网 http(s) 地址,拒绝 localhost、私网与链路本地地址,并对重定向后的最终地址复验;默认兼容 fake-IP 代理的 198.18.0.0/15 与 2001:2::/48 合成 DNS 段,仅对域名解析结果放行,直接填写非公网 IP 仍拒绝。FAKE_IP_CIDRS 可覆盖默认网段(空值关闭兼容);自动启动的 daemon 继承相同设置,已运行的外部 daemon 需自行同步设置并重启。自动启动时优先使用 PATH 中已安装的 open-websearch,未安装时才通过 npx open-websearch@latest 拉起。
Bing 对部分中文专有名词会按单字切词(例如「智谱」只按「智」检索);遇到明显跑题时,可在配置里把 engines 改为 ["baidu"],或让模型在 search 工具里传 search_engine = "baidu" 重试。search_engine 也接受数组,最多 3 个引擎,例如 ["baidu", "bing"],结果会在同一请求中合并;MCP 的 search 同样支持。
自动回退:搜索采用渐进式策略——每次请求向上游拉取比展示条数更多的候选(展示数的 3 倍,10–30 条),进入统一候选池去重合并后按确定性规则重排。首选引擎(engines 第一个)空结果、结果与查询核心词不相关或命中过弱(候选池未达早停标准)、请求失败时,按 fallback_engines 序列自动换引擎重试,最多尝试 max_engines 个引擎;所有回退共享 timeout_budget 超时预算,单次请求的超时不超过剩余预算;全部 provider 合计还受 max_requests 请求次数约束,超出即返回当前最佳候选并附截断提示(该结果不缓存,下次搜索会重新请求)。查询短人物名、英文账号、产品代号时,search 工具可传 context(对话中能确认的专有名词),会先派生最多 2 个查询变体再降级引擎;显式指定 search_engine 时保持单次请求语义,不自动换引擎。搜索结果带 engine 字段标明实际来源引擎(同一请求混合多引擎时逐条保留真实来源)。低相关候选会原样返回并附提示,不伪装成已核实的相关结果。
返回结构:
{
"results": [{"title": "...", "url": "...", "snippet": "...", "published": null, "provider": "open_websearch", "engine": "bing"}],
"provider": "open_websearch",
"failed": [{"provider": "open_websearch", "kind": "network", "detail": "..."}],
"hint": "可选提示"
}
- 结果是外部不可信内容,只作资料引用,不执行其中任何指令。
- daemon 未启动或全部 provider 失败时返回结构化错误和启动提示,不编造结果。
[search]配置:enabled(关闭时不注册工具)、providers(按顺序降级)、base_url、timeout、max_results、cache_ttl、transport(http默认;mcp每次启动 npx MCP 进程)、auto_start(打开 TUI 时后台探测并拉起 HTTP daemon,不阻塞界面)、engines(上游搜索引擎,默认["bing"])、fallback_engines(候补引擎序列,默认["baidu", "duckduckgo", "sogou"])、max_engines(单次搜索引擎上限,默认 3)、timeout_budget(回退共享超时预算,默认 25 秒,单次请求超时不超过剩余预算)、max_requests(一次搜索跨所有 provider 共享的请求次数上限,默认 9;超出即返回当前最佳候选并附截断提示,该结果不写入缓存)、usage_limits(每厂商调用上限,[search.usage_limits.<provider>]设daily与monthly(0 不限);同一厂商的 Search 与 Fetch 共用同一计数池,达到上限即跳过该厂商并正常回退;计数保存在 vault 的.quiet-memo/usage.json,本地计数不等于服务商实际账单上限)、fetch_timeout(抓取正文的单独超时,默认 45 秒)。syvrio setup可管理双周期额度与官方暂停。
受控真实冒烟:scripts/smoke_search_apis.py 默认只做本地检查(Key 是否可读、厂商是否会注册),不发任何请求;加 --provider <厂商> --operation search|fetch --live 才对单一厂商发起最多 --max-requests(默认 1,上限 10)次真实请求,输出脱敏报告(成功与否、结果数或正文长度、错误类型、耗时与待验证字段)。Key 只从环境变量或系统凭据读取,不回显。网页抓取由独立的 [fetch] 配置控制:providers 是抓取正文用的 provider 顺序(默认 ["open_websearch"]),与搜索的 provider 顺序相互独立;配置了 Key 的官方厂商(tavily / exa / you / volcengine)加入该列表后才参与抓取。
auto_start启动的 daemon 在 Windows 下隐藏控制台窗口;退出 TUI 后继续常驻,下次直接复用。- 搜索结果缓存为
.quiet-memo/search-cache.json,属于派生数据,可删除。普通成功结果缓存 24 小时(cache_ttl);「今天/最新/latest」等时效性查询与空结果只短缓存(10/5 分钟),上游失败一律不入缓存。
抓取按 [fetch].providers 独立选择厂商;官方抓取与 open-websearch 抓取均使用 search.fetch_timeout,搜索仍使用 search.timeout。open-websearch 抓取要求 HTTP transport,其他已配置的官方抓取不受其 transport 限制。
写入规则
| 情况 | 行为 |
|---|---|
| 置信度 ≥ 阈值、非敏感、无冲突 | 直接写入 |
| 置信度低于阈值 | 进入待确认队列 |
| 数值/否定/高相似度冲突 | 进入待确认队列,保留冲突条目 ID |
| 敏感内容 | 进入待确认队列 |
| 密码、验证码、API Key | 直接拦截,不落盘 |
| 文本完全重复 | 跳过 |
记忆按主题存为 memories/<topic>.md,条目带稳定 ID、状态、时间戳、来源和置信度:
- 2026-10-22T19:42:50 — 在找市区的房子 `id=mem-20261022-194250-8f1e` `status=active` `source=session:s-...` `confidence=0.95` `session=s-...` `message=m-...`
更正采用“新条目 + supersedes”,旧条目状态改为 superseded;删除是软删除 deleted,操作写入 .quiet-memo/audit.jsonl,Git 可回滚。
来源等行尾标签值含反引号或换行时,以 ~qm-escaped~ 前缀加百分号编码存储,读取时还原;普通标签格式不变,条目 ID 保持稳定。
抽取与导入支持可选的 context JSON 行尾标签。无依据时字段缺省,旧 Markdown 无需迁移:
| 字段 | 含义 |
|---|---|
event_time |
事件或事实发生日期,与条目的写入时间 timestamp 分开 |
valid_from / valid_to |
明确提供的生效起止日期;未给结束时间不表示永远有效 |
time_text |
时间原话;无法确定参照日期的“去年”“现在”等只保留原话 |
location / location_kind |
地点与类型:event(事件地点)或 residence(居住地),须成对提供 |
emotion / emotion_source / emotion_at |
明确表达的情绪原话,来源仅 explicit;event 表示当时,expression 表示如今谈起的感受,缺省为后者 |
事实日期只接受 YYYY、YYYY-MM、YYYY-MM-DD,保留原有精度,不补猜月日或转换时区。地点不从设备采集,语气推断、反讽和模糊情绪不作为情绪事实写入。正文仍保留这些限定,上下文目前不参与检索过滤或重排。上下文与正文一起检查凭据,正常确认会保留上下文;改写后确认或手动更正不会沿用可能已过期的旧上下文,原候选仍可审计。
推断基础接口 MemoryService.propose_inference(text, source_ids, kind) 将假设单独追加到 .quiet-memo/inferences.jsonl,类型为 profile 或 emotion,新记录始终为 hypothesis。只接受当前有效的事实条目 ID,来源去重;同类型、同规范化文本、同一组证据重复提交返回原记录,不增加置信度或重复追加。推断 ID、已删除或已被更正的来源不能作为新证据。
这是后端基础能力,尚无 CLI/TUI/MCP 推断入口,不自动生成、确认或注入聊天。模型声明保留 confirmed / rejected / superseded 状态,但用户确认流程、已有推断的来源失效处理与损坏日志恢复尚待实现;推断不会进入事实检索。
/pending 的“改写后确认”先校验最终文本,再直接写入一条记忆,不先写原文再更正;冲突候选仍通过 supersedes 替代旧条目。原候选保留在 resolved.jsonl,审计记录以 text_override 保存改写文本。空白或识别出的凭据被拒绝时,候选与旧条目保持不变。
确认过期的冲突候选时,沿替代链更正当前有效版本;原记忆已删除、缺失或替代链不明确时拒绝写入并保留候选。会话中的用户消息、助手回复、摘要、标题及工具参数在追加落盘前隐藏已识别凭据;用户新消息也会先脱敏再送模型。不自动改写已有会话或 Git 历史。
凭据检测结合赋值和分隔语境,允许“密码忘记了怎么办”“验证码一直收不到”等描述,同时拦截含特殊字符的密码、中文明确赋值及验证码后紧接中文的常见形式。检测是启发式的;明确写成凭据赋值的歧义文本仍保守拦截,不应把它当作完整的敏感信息防泄漏系统。
结构
src/syvrio/
├── app/ cli.py, server.py, tui.py, chat_app.py, chat_commands.py, chat_flow.py,
│ chat_widgets.py, chat_input.py, chat_theme.py, command_catalog.py,
│ actions.py, ui.py, session_ui.py
│ # CLI / Textual TUI / FastMCP 入口
├── agent/ runtime.py, prompts.py, context.py, tools.py,
│ session.py, recall.py, file_tools.py # Agent 循环、工具、会话与文件分析
├── memory/ service.py, store.py, models.py, queue.py,
│ policy.py, detect.py, extractor.py, audit.py, inference.py
│ # 记忆领域与写入裁决
├── retrieval/ base.py, keyword.py, vector.py, hybrid.py
│ # Retriever 接口 + BM25/向量/混合
├── llm/ client.py, summarizer.py, commit_summary.py
│ # LiteLLM 适配、会话/提交摘要
└── infra/ config.py, providers.py, gitops.py, tokens.py,
layout.py, dialogs.py, documents.py, search/ # 配置、文档转换、联网搜索
依赖方向:app → agent → memory → retrieval → infra,memory/agent → llm → infra。
retrieval 会只读 memory 的 models、store、detect(条目读取、归一化与字面覆盖判断),这是 memory ↔ retrieval 的已知回读;写入与裁决仍只由 memory 负责。
开发约定(代码风格、存储不变量、测试与文档同步)见 AGENTS.md。
README 的界面演示与截图保存在 docs/assets/,不包含个人记忆库数据。
- 检索默认 hybrid:jieba + rank-bm25 与向量余弦两路结果做 RRF 融合;向量由 fastembed 本地推理(可选 extra)或 embedding API 计算,缓存为
.quiet-memo/vectors.npz派生数据(vault 内已 gitignore,删除后自动重建;换 embedding 模型自动失效)。向量后端不可用时回退纯 BM25,/status和qm status显示当前检索模式。 - token 预算用 tiktoken 估算,离线失败时回退字符估算。
- 会话压缩、记忆裁决、来源链是自研核心;模型适配交给 LiteLLM,供应商选择与密码输入用 questionary,Key 用 keyring。
测试
使用项目独立虚拟环境安装锁定依赖,再运行测试:
uv sync --frozen
uv run pytest
uv.toml 将依赖缓存放在已忽略的 .cache/uv;缓存齐全后可用 uv sync --frozen --offline。VS Code 打开项目后选择 .venv,测试面板支持 pytest,并提供“调试当前测试文件”和“调试全部测试”配置。测试夹具隔离配置、vault 与凭据,不需要真实 API Key。
如果受限 Windows 环境禁止回环 TCP,默认 asyncio 可能卡在 socketpair。使用锁定的 pytest-asyncio,可在 PowerShell 中先设置 $env:QUIET_MEMO_TEST_PIPE_LOOP = "1" 再运行测试,改用本地管道唤醒 Proactor;仅影响测试,不开放网络权限,也不修改应用运行时。普通 Windows 和 Ubuntu 继续使用默认事件循环。
局部改动按影响范围运行分类测试,提交前再跑全量:
uv run pytest -m ui
uv run pytest -m agent
uv run pytest -m memory
uv run pytest -m retrieval
uv run pytest -m "cli or config"
uv run pytest -m "mcp or search"
uv run pytest
分类为 ui(TUI)、agent(运行时/会话/上下文)、memory(存储/抽取/裁决/队列)、retrieval(本地检索)、cli、config、mcp、search(联网搜索)。LLM 路径用固定抽取器和假模型测试;未接真实 API Key 时不声称已完成线上验证。
解析与写入裁决的离线合成回归可单独运行,也随 pytest 执行:
uv run python evals/memory_eval.py
该基准覆盖抽取输出解析、冲突、日期精度、地点、显式情绪和上下文凭据拦截;它固定模型输出,不衡量真实模型的语义抽取效果。范围与局限见 evals/README.md,交接状态见 docs/HANDOFF.md。
检索评测
evals/ 提供可复现的合成语料基准(456 条 / 27 例,无任何个人数据):
uv run python evals/retrieval_eval.py
2026-10-30 重跑,合成库 456 条记忆 / 27 例:
| 检索方式 | Hit@3 | Hit@5 | MRR@10 |
|---|---|---|---|
| keyword | 74.1% | 74.1% | 0.722 |
| vector | 92.6% | 92.6% | 0.913 |
| hybrid | 92.6% | 92.6% | 0.913 |
真实库 882 条有效事实 / 24 个模型生成问题:
| 检索方式 | Hit@3 | Hit@5 | MRR@10 |
|---|---|---|---|
| keyword | 95.8% | 95.8% | 0.889 |
| vector | 91.7% | 95.8% | 0.814 |
| hybrid | 91.7% | 95.8% | 0.842 |
真实题集由模型从随机事实生成,不是人工标注金标准。历史 797 条题集结果、方法、耗时与已知弱点见 evals/README.md。
Roadmap
完整待办以 GitHub Issues 为准。以下按大致实现难度由低到高排列;实际开发顺序可按收益与依赖调整,所有新增功能均服务于个人日常聊天记忆,不扩展成通用工作 Agent。
| 难度 | 方向 | 规划 |
|---|---|---|
| 低~中低 | 记忆上下文:时间、地点、情绪 | 基础字段与存储链路已实现;待补原始时间锚点、相对时间解析及推断情绪 |
| 低~中 | 推断独立存储与用户确认 | 独立存储与证据去重已实现;待补用户确认、拒绝、纠正及来源失效处理 |
| 中~中高 | 事实时间演化与多维召回 | 区分历史变化与真正冲突;用时间、地点、情绪辅助现有混合检索 |
| 高 | 梦境记忆 / Dreaming | 后台增量回顾与整合,产出可审查的候选推断,异常可恢复 |
| 高 | 动态用户画像 | 基于来源证据持续维护个人偏好、经历与近期状态,用户可纠正 |
| 很高 / 长期 | 跨 AI 客户端主动召回 | 在客户端能力允许时,无需显式提醒即可适时调用个人记忆 |
| 持续工程 | 记忆质量评测与回归 | 扩展抽取/冲突、时间变化、情绪推断、隐含召回等合成测试,不以一次发布为终点 |
其他待办:
- 真实模型 dogfood 与成本统计
- 每日定时提交守护进程
qm consolidate子命令:手动或系统计划任务触发整库补沉淀(启动时自动补记与自动提交已实现)
表中已标明基础实现与剩余规划;当前支持的行为和边界以 README 其他章节为准。
会话浏览、搜索与恢复统一使用 /sessions。聊天中直接说“你记得……吗”或“记住……”,由 Agent 调用 recall / memorize;不提供对应的 TUI 斜杠命令。命令行管理入口保持可用。
自动记忆召回按个人话题和连续追问触发;通用问题跳过预取,模型仍可按需调用 recall。auto_recall=0 关闭预取。
TUI 固定界面文案统一使用英文,聊天内容保留原语言。搜索引擎的自动回退规则见联网搜索;显式指定引擎不自动替换。引擎失败不会显示为零结果或写入结果缓存。
Windows 交互终端输入框使用原生细竖线光标,以配合中文输入法组字;拼音阶段的光标表现取决于终端与输入法。
显式指定搜索 limit 可覆盖 max_results 默认条数,Agent 搜索最多返回 15 条;缓存命中仍保留低相关候选提示。
搜索 API 本地额度与官方暂停
默认本地请求次数保护如下,直接编辑 TOML 启用厂商也会生效;不是官方免费套餐或账单额度。
| Provider | 每日 | 每月 |
|---|---|---|
| baidu_search | 50 | 0 |
| tavily | 0 | 800 |
| exa | 0 | 1000 |
| you | 0 | 1500 |
| volcengine | 0 | 450 |
| open_websearch | 0 | 0 |
0 表示该周期不限。配置以 [search.usage_limits.<provider>] 的 daily、monthly 覆盖默认值,显式 0 会保留;两周期任意一项耗尽即跳过。Search/Fetch 共池,缓存命中不计数,已发出的失败请求保守计数。按运行机器本地时区的自然日/月重置;状态保存在 .quiet-memo/usage.json,同进程检查与记账互斥,跨进程不保证严格上限。
[search.usage_limits.tavily]
daily = 0
monthly = 800
旧 period/max_calls 配置继续读取,显式旧上限优先于默认值;下次保存写为双周期格式。旧计数保留其已知周期,另一周期的历史用量无法推算,界面会注明未知,之后从实际观察到的请求开始累计。Tavily Credits、Exa 美元 Credits、You.com 余额与请求次数不等价,可能在本地次数用完前已耗尽余额,也可能在达到本地上限前就产生费用。
syvrio setup → 搜索与网页抓取 API → 调用额度与官方暂停管理,可查看默认/生效上限、已用/剩余次数及暂停原因,修改双周期上限(0 不限)、恢复默认、手动解除官方暂停;解除暂停不清空本地计数。首次启用不再统一限制每天 20 次。
只有已核实的官方额度/余额/支出上限错误才持久暂停,普通 QPS 限流、超时、5xx 和鉴权失败不触发长期暂停。暂停与本地次数耗尽会显示不同原因,下一可用厂商仍可接替;显式指定暂停厂商时不会替换厂商,已有缓存仍可读取。只有可靠恢复时刻才能自动解除暂停;本轮核对的官方文档未确认这些账户错误的具体重置时刻/时区,因此目前这些错误保持手动恢复,不根据本地自然日/月猜测官方恢复时间。
稳定性边界
会话列表和启动补沉淀会报告并隔离异常文件,直接加载仍报错,原始字节保持不变;损坏尾行继续通过追加标记恢复。人工确认、更正、拒绝和软删除在普通写入异常时,对涉及的主题及决策日志执行补偿回滚,回滚成功后可安全重试;回滚失败会显式报告。这不是跨进程终止、断电或多进程并发的原子事务,仍应单写入者使用并保留 Vault Git 检查点。
Search/Fetch 同进程共享额度计数,但多个 QM/MCP 进程同时运行时不保证跨进程原子性;本地额度是保守防护,不是厂商账单保证。可选的 npx open-websearch@latest 兜底不受 Python 锁文件冻结:需复现环境时,应自行安装并保留经过验证的上游版本,已安装命令仍优先使用。本轮冻结不包含干净上游包或动态网站的真实 API 验证。
Windows 下 CLI 重定向的标准输出和错误输出采用 UTF-8;原生终端处理及系统持久设置保持不变。
Metadata
Release files for syvrio 0.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| syvrio-0.3.3.tar.gz | 770.4 kB | With provenance | Details for syvrio-0.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| syvrio-0.3.3-py3-none-any.whl | Python 3 | none | any | Details for syvrio-0.3.3-py3-none-any.whl |
Total release size: 968.8 kB
Release files / syvrio-0.3.3.tar.gz
| Download URL | syvrio-0.3.3.tar.gz |
|---|---|
| Size | 770.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d8696e2ffadb4ed25ceea30494089a84dd59002ed5fdd6523e2811718315a95c
|
|
BLAKE2b-256 checksum How to use checksums |
10ddb748bdafef18cc7c7b55fcdb7c557bb71c076eb69e296f0825561f01ada4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logRelease files / syvrio-0.3.3-py3-none-any.whl
| Download URL | syvrio-0.3.3-py3-none-any.whl |
|---|---|
| Size | 198.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
61cbd72678c107e51ef9525fd66924df71fef638f78bf34f8f2d99f3079fb128
|
|
BLAKE2b-256 checksum How to use checksums |
1f06296aef4bf52aa352fc2f5ae77f90972dfe08380791386e2eac521213b479
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logSecurity for syvrio 0.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for syvrio-0.3.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.