本地终端会话记忆库：把**完整会话（命令 + 输出摘录）**归档进本地 JSONL 库， 日后用一句“我上次是怎么修好的？”就能检索出当时的片段。纯 Python 标准库，零依赖。
| 项目 | 它做什么 | 与 termemory 的差异 |
|---|---|---|
| Atuin | 用 SQLite 数据库替换 shell 自带历史，为每条命令附加上下文元数据（退出码、耗时、cwd、主机名、会话 ID），并提供端到端加密的多机同步与全屏交互搜索 UI | Atuin 索引的是命令本身及其元数据，不保存命令的输出；termemory 则按轮次归档完整会话文本（含输出摘录），支持对过去会话做“复盘式”检索问答 |
| histdb | 把 zsh 历史写入 SQLite，逐条记录命令的时间戳、执行时长、退出码、所在目录 | histdb 同样只是命令级历史索引；termemory 的最小单位是“一轮命令+输出”，能回答“当时报错是什么、最后怎么修好的”这类需要看输出的问题 |
注：Atuin 一行依据其官方 GitHub README 原文 —— “Atuin replaces your existing shell history with a SQLite database, and records additional context for your commands” （记录 exit code、duration、cwd、hostname 等上下文）。两行共同点：都只索引命令， 不归档输出；termemory 补的正是“完整会话含输出的复盘问答”这块空白。
capture：导入终端会话文本，自动切分为轮次块（命令行 + 输出段），存入本地 JSONL 库search：确定性词法检索（bigram 重叠评分），返回 Top-N 会话片段，带时间戳与标签ask：问题 → 关键词 → 检索 → 拼接最相关片段生成“离线答案包”（明确标注这是检索拼接而非 LLM 生成；默认纯离线，--llm仅提示外接方式）stats：会话数 / 轮次块数 / 标签分布
- Python ≥ 3.10（仅标准库，无任何第三方依赖）
- Windows / macOS / Linux 均可
# 1) 归档一份会话日志（可重复 --tag 打多个标签）
python -m termemory capture --file examples/session.log --tag demo
# 2) 词法检索
python -m termemory search pip --top 5
# 3) 提问式回忆（离线答案包，非 LLM 生成）
python -m termemory ask "上次 pip 装不上是怎么解决的?" --top 3
# 4) 库概况
python -m termemory stats默认库文件为当前目录下的 .termemory/library.jsonl；可用全局参数
--db PATH 或环境变量 TERMEMORY_DB 指定其他位置。
python -m termemory capture --file LOGFILE [--tag TAG]... [--db PATH]
python -m termemory search KEYWORD [KEYWORD ...] [--top N] [--db PATH]
python -m termemory ask QUESTION [QUESTION ...] [--top N] [--llm] [--db PATH]
python -m termemory stats [--db PATH]
| 码 | 含义 | 示例 |
|---|---|---|
| 0 | 正常（含“空库友好提示”、“未找到匹配”等情形） | 检索无结果仍返回 0 |
| 1 | 数据错 | --file 文件读不到、库文件 JSONL 记录损坏 |
| 2 | 用法错 | 未知参数、缺少必需参数、裸调用 |
识别常见提示符行作为轮次起点：$ cmd、# cmd（root）、user@host:~$ cmd、
PS C:\...> cmd、C:\...> cmd。提示符后的非空行归入该轮输出段；
首条提示符之前的非空内容作为 preamble 块保留。
单轮输出超过 40 行时按“头 10 行 + 省略标记 + 尾 30 行”截取（确定性规则）。
编码兜底顺序：BOM 嗅探（UTF-8/16/32）→ 严格 UTF-8 → 严格 GB18030（兼容 GBK）→ UTF-8 lossy（替换坏字节）。GBK 老日志可直接导入不炸。
JSON Lines，一行一个会话对象（键排序、UTF-8、\n 结尾，跨平台序列化一致）：
{"blocks": [...], "captured_at": "2025-01-01T00:00:00Z", "id": "<sha1前12位>",
"schema": 1, "source": "session.log", "tags": ["fix"], ...}会话 id 由 source + tags + blocks 内容哈希生成（不含捕获时间）：
同一份内容重复 capture 会被识别为重复并跳过。
同一份库 + 同一个查询词，search/ask 输出永远逐字节一致：
评分相同时按 captured_at → session id → block index 依次打破平局，
不使用任何随机性或哈希序迭代。
python -m unittest discover -s tests -q测试覆盖：切块边界（CRLF/BOM/空文件）、检索确定性双跑一致、ask 空库友好、 stats 分布、GBK 子进程冒烟等 40+ 例。
MIT © 2025 ox-alpha
pip install -e .$ python -m termemory --help
usage: termemory [-h] [--version] {capture,search,ask,stats} ...
Local terminal-session memory bank: archive whole sessions (commands + output
excerpts), then recall them offline.
positional arguments:
{capture,search,ask,stats}
capture archive a terminal session log file
search deterministic lexical search over archived blocks
Issues and PRs welcome - run pytest locally before submitting.