. 先想清楚：记忆有两种。存法完全不同

痛点：开发者常把「对话历史」和「长期记忆」混为一谈，导致存储方案选错、查询慢、数据冗余。

聊「记忆」之前，得先把两个被混在一起的东西拆开。

• 对话历史——你和 Agent 这一来一回的原始记录，逐字逐句、带工具调用、带 token 用量。它是流水账，要的是完整、可回放.
• 长期记忆——从大量对话里提炼出的「事实」：你习惯用 pnpm 不用 npm、项目采用 Compound Pattern、你讨厌中文注释。话说回来，它是结论，要的是精炼、可复用。下次换会话也要记得，

这两种东西在 catbuddy 中用完全不同的方式存：

. 对话存哪：JSONL，而不是 SQLite

痛点：#1 开发者担心 JSONL 随机访问慢；老实说，#2 SQLite 编译麻烦、二进制不可观测；#3 多网站维护成本高，

"你们为什么不用 SQLite？"——这是 catbuddy 架构里被问得最多的问题。几乎每个后端背景的人看到 catbuddy 拿一堆 .jsonl 文件存聊天记录，第一反应都是："认真的？"

JSON Lines: 每行一个独立的 JSON 对象的纯文这篇文章件。说起来，没有外层 。行与行互不依赖——可以逐行追加，也可以逐行读取。

选存储，先看访问模式

操作	频率	数据量
追加新消息	↑ 每轮一次	↑ 1~ 条
读当前会话历史	↑ 每轮一次	↑ 最近 100~200 条
列出所有会话    切换会话时只读第一行    随机访问单条消息几乎没有

洞察：No complex queries。no joins,no concurrent writers. JSONL 的顺序写读恰好匹配这种模式。怎么说呢，

JSONL 长什么样：第一行是索引，后面是数据

The session file lives at `~/.catbuddy/workspace/sessions/`. Example:

{
说到"key"，"desktop:main","title":"前端重构讨论","preview":"我觉得应该...","created_at":"2024-01-01T12:00:00Z","updated_at":"2024-01-02T08:30:00Z","last_consolidated":null,"metadata":{}
}
至于{"id"。1,"sessionKey":"desktop:main","role":"user","content":"我觉得应该用 Compound Pattern","timestamp":"2024-01-01T12:01:00Z"}
再看{"id"，2,"sessionKey":"desktop:main","role":"assistant","content":"同意，但需要注意...","timestamp":"2024-01-01T12:02:00Z"}
...

• #第一行元数据：*标题*、*预览*、*时间戳*等，只读首行即可列出会话列表，实现类似索引功能。不过，
• #后续行消息：*每条消息占一行*。并冗余保存 `sessionKey`*,即使单文件迁移也能自识别所属会话。

再看写入的安全，一个 rename 就够了

Pain point:#4 并发写安全性担忧。Catbuddy 使用单写者模型，通过“全文件重写 + 原子 rename”保证一致性。

const lines =;怎么说呢，const tmp = filePath + '.tmp';fs.writeFileSync + '
','utf8');// 写临时文件
fs.renameSync;// 原子替换
// POSIX rename 保证读取者要么看到旧文件，要么看到新文件

This approach eliminates need for WAL journals and transaction logs while keeping write latency around ~5ms for ~200KB files.

从不让它无限长来看。条上限 + 摘要压缩

The system caps each session at `MAX_MESSAGES` = 5000 条 . When exceeded,oldest messages are trimmed and fed into a summarizer before deletion.

if {
messages.splice;话说回来，// 丢最旧
}

This ensures that raw logs stay bounded while essential facts survive in long‑term memory via Consolidator and Dream pipelines.

. Dream：猫睡着了也在偷偷学习

Pain point:#5 跨会话记忆缺失；#6 手动触发记忆提取繁琐；#7 后台任务容易因格式错误导致数据丢失。

底座的观点是，游标驱动的增量读取

appendHistory {
this._cursor += 1;const row = { cursor: this._cursor。content: entry,at: new Date.toISOString };fs.appendFileSync + '
','utf8');fs.writeFileSync,String);return this._cursor;}
readEntriesSince {
// 返回 cursor> lastCursor 的所有记录，实现“断点续传”
}

Dream 的两阶段：提取 + 巩固

Phase – 提取

const newEntries = this.store.project.readEntriesSince;
if return，

this.processedCursor = Math.max,this.processedCursor);

const prompt = ${extractionGuidance} Existing MEMORY.md: ${existingMemory.slice} New entries : ${newEntries.slice.map}).join} ${FORMAT_SUFFIX}`;const llmResult = await callLLM;

• *现有记忆一起喂回去*: LLM 能判断是更新还是新发现。
• *游标提前推进*: 实现 “至少一次” 而非 “恰好一次”。
• *限流*: 防止一次性喂太多导致 token 爆炸。
• *格式指令*: 要求 LLM 输出固定区块 `

Phase – 巩固

• *第一级·验证*: 检查非空、包含两块标题且每块都有实质内容。
• *第二级·重试*: 若格式错误。将上一次输出嵌入提示词，让 LLM 再尝试一次。
• *第三级·降级*: 重试仍失败。仅在内容极短时才放弃，否则保留原始输出作为“可能有料”。怎么说呢，

LayeredMemory：你的事归你。项目的事归项目

export function appendLayeredMemory {
const { userProfile,projectContext } = splitMemorySections;其实，if {
appendToMemoryFile;return，}
if
appendToMemoryFile;说起来，if
appendToMemoryFile;话说回来，if
appendToMemoryFile(globalWorkspace。opts.label,opts.summary.trim,"User Profile");}

• 关于「你」的事实 → 写入全局 MEMORY.md。说起来，
• 关于「项目」的事实 → 写入对应工作空间下的 memory/MEMORY.md。*切不出区块 → 整段塞进全局作为兜底。
} \

AutoCompact：调度何时学习？空闲越久、消息越多优先级越高

private _priorityWeight {
const idleMinutes = Math.max(0,- Date.parse) / 60000);const msgCount = info.metadata?.msgCount，?0，return idleMinutes * msgCount;// 空闲时间 × 消息数量
}

• 每轮最多压 X 个。其实，
• 失败指数退避避免“有毒”会话反复占资源。
• 跳过活跃会话 确保后台任务不抢前台交互资源。<\/ul>

. 云端怎么对齐：JSONL 是真相，MySQL 是缓存

Pain point:#8 多端同步冲突难以解决；#9 本地磁盘不可达时如何展示历史记录；#10 数据一致性验证成本高。

两套存储，一套类型

<>

<="">	<="" 行号=""> < th=""> <\/tr> <\/ad>
gateway_sessions<\/td>	- 第一行元数据<\/td>	会话元信息与消息记录同步<\/td> <\/tr>
gateway_session_messages<\/td>	- 第 N 行消息记录<\/td> <\/tr>
gateway_users<\/td>	<\/td>	User auntication<\/td> <\/tr>\ <\/tbody>\ <\/table>

The two sides share same TypeScript types。ensuring field‑to‑field mapping.

• Desktop JSONL 为 Source of TruthIf MySQL crashes you still have a pristine local copy.
• Gateway MySQL 为分发缓存The only purpose is to let web clients read conversation.
\
• basing conflict resolution on timestamps (LWW – Last Write Wins） ensures deterministic merges without heavy consensus algorithms.
\ <\/ul>

// Desktop receives remote update
if {
return;// discard older payload
}
\/\/ MySQL side uses ON DUPLICATE KEY UPDATE with updatedAt comparison
\
\
\
\
\
\
\
\​

This simple rule works perfectly for a single‑user chat app where concurrent edits are virtually nonexistent.

. 复盘：如果重来一次

• Pain point revisited: 每次 addMessage 都整文件重写虽已足够快，但仍有调整空间。)
\
• BUT we chose not to change because current solution has been stable for over a year across many users—optimizing a non‑issue would be “炫技”，而不是工程价值最高的投入。
\ <\/ul>

This article covered:

1. The storage decision: Why catbuddy prefers JSONL over SQLite—access pattern fit‑match eliminates unnecessary complexity while preserving observability and safety via atomic renames and line‑based indexing.
\ The long‑term memory pipeline: AUTO COMPACT → DREAM → LAYERED MEMORY. All components cooperate to turn raw chat logs into reusable facts without ever exposing crashes to user.\ The cloud alignment strategy: The desktop’s JSONL remains source of truth; The gateway’s MySQL acts as a cache; LWW timestamp arbitration guarantees deterministic sync across devices.\ <\/ol>

下一篇预告：多家大模型 API 差异封装、故障自动转移与三层重试机制，让你的 Agent 在任何环境下都保持韧性。怎么说呢，

---