1. 为什么 AI Agent 需要一个像样的记忆目录先说结论AI Agent 的记忆系统本质上是磁盘上的一套目录结构加写入规范而不是模型脑子里记住的东西。上下文窗口Context Window只是工作台文件才是仓库。你不写进文件的东西Agent 下次醒来就等于从来不知道。我见过太多 Agent 项目卡在同一个坑里Session 1 里做了重要决策 A没落盘对话变长触发压缩Compaction早期内容被丢掉Session 2 启动Agent 对决策 A 一无所知于是重复讨论、重复踩坑。跨频道更明显Telegram 里聊过的结论Discord 里的 Agent 完全隔离因为它俩根本不在一个 session。所以生产级记忆系统的核心原则只有一条文件等于事实来源。所有重要信息实时写入文件Agent 每次启动从文件读状态不依赖“记得去检查”而是靠 cron、heartbeat 这类系统触发。这篇要交付的是可直接复制的目录骨架、settings.json与config.toml配置、以及验证接入是否生效的具体动作。适合正在给 Agent 搭记忆层、又不想一上来就上重型数据库的开发者。目录结构我按三层来分短期NOW.md、中期每日日志、长期知识库再配一个.archive/冷存储。下面从接入通道开始一步步把骨架搭起来。2. TaoToken 统一 Key 接入把模型通道先固定下来记忆系统本身不依赖某个特定模型但 Agent 每次启动要读文件、做提炼、跑 CRUD 回写这些动作都要调模型。如果每个 Agent、每个脚本各配一套 Key 和 base_url配置会迅速失控。我的做法是先用 TaoToken 把模型通道统一成一份配置记忆系统只认这一个入口。TaoToken 在这里扮演的是统一 API 通道一个 Key、一个 base_url兼容 OpenAI 风格的接口Agent 主程序、夜间反思脚本、日志同步任务都走它。这样目录结构里所有涉及模型调用的地方配置项都能收敛到同一处迁移和排障都省事。你需要先拿到 Key。登录官网后进入控制台在 API Keys 页面创建一个新 Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_systemAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_system创建时建议按用途分开命名比如agent-memory-main、agent-memory-reflect方便后面按 Key 排查是哪个环节出的问题。Key 只在创建时完整显示一次复制后立刻存进环境变量或密钥管理工具不要硬编码进仓库。统一入口的 base_url 是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容的 base_url 使用。模型名按你实际开通的填比如gpt-4o、claude-3-5-sonnet这类具体以控制台模型列表为准。提示记忆系统的模型调用分两类——日间轻量写入追求快和夜间深度反思追求准。可以给这两类配不同的模型但都走同一个 base_url 和同一套 Key 体系配置上只区分 model 字段。3. 目录结构骨架三层记忆加冷存储先把完整目录树贴出来这是后面所有配置的落点。你可以直接复制成项目初始结构workspace/ ├── NOW.md # 短期状态仪表盘覆写式 ├── AGENTS.md # Agent 操作手册 ├── HEARTBEAT.md # 心跳巡检流程 ├── settings.json # 主配置模型通道 记忆后端 ├── config.toml # 记忆系统参数 └── memory/ ├── INDEX.md # 知识导航启动必读 ├── 2026-02-26.md # 每日日志追加式 ├── decisions/ # 战略决策永久保留 │ └── 2026-02-14-architecture-v2.md ├── lessons/ # 可复用教训按主题 │ └── cron-discipline.md ├── people/ # 人物/Agent 画像 │ └── user-profile.md ├── projects/ # 项目状态追踪 │ └── memory-system.md ├── preferences/ # 用户偏好与边界 │ └── user-preferences.md ├── reflections/ # 每日自省 │ └── 2026-02-26.md ├── actions/ # 任务生命周期 │ ├── open/ │ ├── in-progress/ │ └── done/ └── .archive/ # 冷数据搜索引擎不索引 ├── 2026-01-15.md └── reflections/三层职责要分清。短期层NOW.md是唯一允许覆写的记忆文件记录当前状态、优先级、阻塞项每次 heartbeat 用 Write 覆写只保留当天完成项它是 Compaction 后的救生筏。中期层是memory/YYYY-MM-DD.md每日日志追加式、永不覆写格式统一为### HH:MM — 标题方便扫描。长期层是INDEX.md加结构化子目录存的是从事件里提炼出的可复用知识不是原始流水。.archive/用点号开头是有讲究的。语义搜索引擎扫描文件时通常会跳过以.开头的目录这意味着memory/2026-01-15.md会被索引而memory/.archive/2026-01-15.md自动被跳过。这是一个零配置的冷热分离方案不需要改搜索引擎的排除规则靠命名约定就实现了。知识文件要带 YAML frontmatter这是健康度检测的基础--- title: Cron 调度纪律 date: 2026-02-13 category: lessons priority: status: active last_verified: 2026-02-26 tags: [cron, automation, reliability] ---priority决定检索排序和归档保护status标记可信度last_verified用于过时检测。状态流转是active → superseded被新版取代或active → conflict发现矛盾待裁决。4. 可复制配置settings.json 与 config.toml配置分两个文件。settings.json管模型通道和记忆后端开关config.toml管记忆系统的行为参数。分开的原因是前者可能被多个 Agent 共享后者更贴近记忆系统本身。先看settings.json{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultModel: gpt-4o, reflectModel: gpt-4o, timeoutMs: 60000 }, memory: { backend: qmd, workspace: ./workspace, qmd: { searchMode: query, update: { interval: 5m, onBoot: true }, limits: { timeoutMs: 15000 } } } }apiKeyEnv指向环境变量名而不是明文 Key这是必须的。defaultModel用于日间写入reflectModel用于夜间反思可以按需换成更强的模型。searchMode设为query会同时跑关键词和向量检索再做重排对中文更友好代价是慢一些。再看config.toml把记忆系统的生命周期参数集中管理[memory.layers] now_file NOW.md daily_log_dir memory index_file memory/INDEX.md archive_dir memory/.archive [memory.write] timestamp_tz Asia/Shanghai log_format ### {time} — {title} append_only true allow_overwrite [NOW.md] [memory.lifecycle] heartbeat_interval 45m daily_sync_at 23:30 reflection_at 23:45 gc_cron 0 0 * * 0 [memory.retention] daily_log_days 30 reflection_days 30 actions_done_days 14 stale_threshold_days 30 protected_dirs [decisions, people, preferences, projects] [memory.temperature] w_age 0.5 w_ref 0.3 w_pri 0.2 decay_lambda 0.03 hot_threshold 0.7 cold_threshold 0.3allow_overwrite只列了NOW.md其他文件一律追加这是防止数据丢失的硬约束。protected_dirs里的目录永不归档decisions、people、preferences属于核心记忆。温度模型的三个权重加起来是 1.0decay_lambda取 0.03 对应约 23 天半衰期。环境变量这样设置export TAOTOKEN_API_KEY你的Key export MEMORY_WORKSPACE$(pwd)/workspace写入脚本memlog.sh是日间追加的入口时间戳从系统取避免模型幻觉时间#!/usr/bin/env bash set -euo pipefail MEMORY_DIR${MEMORY_DIR:-./workspace/memory} TODAY$(TZAsia/Shanghai date %Y-%m-%d) NOW$(TZAsia/Shanghai date %H:%M) FILE$MEMORY_DIR/$TODAY.md TITLE${1:?Usage: memlog.sh \Title\ \Body\} BODY${2:-} if [[ ! -f $FILE ]]; then printf # %s\n $TODAY $FILE fi { printf \n### %s — %s\n $NOW $TITLE [[ -n $BODY ]] printf \n%s\n $BODY } $FILE echo Logged to $TODAY.md at $NOWset -euo pipefail保证错误不静默失败追加用而不是从脚本层面锁死追加语义。5. 验证接入是否生效三个具体动作配置写完不代表生效要动手验证。我按从通道到记忆的顺序给三个动作。第一个动作验证模型通道通不通。用 curl 直接打一次对话接口curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 只回复两个字通了}] } | head -c 400返回体里choices[0].message.content有内容说明 Key 和 base_url 都对。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 有没有多写路径。第二个动作验证写入链路。跑一次 memlogchmod x memlog.sh ./memlog.sh 接入验证 TaoToken 通道打通记忆写入测试。 cat workspace/memory/$(TZAsia/Shanghai date %Y-%m-%d).md你应该看到文件里出现### HH:MM — 接入验证加正文。再跑一次确认是追加而不是覆盖两次条目都在。第三个动作验证检索链路。等 QMD 完成一次重扫默认 5 分钟或重启触发onBoot然后查询qmd query 接入验证 --dir ./workspace/memory --limit 3能命中刚写的日志说明索引同步正常。如果查不到先确认文件不在.archive/下再确认update.interval是否生效。注意中文检索有个已知限制。FTS5 默认的 unicode61 分词器不切中文盘前简报这种连续汉字会被当成一个长 token搜盘前可能 0 结果。变通办法是走query模式向量语义或者在写入时有意用空格分隔关键词。6. 本篇常见错排查报错一401 Unauthorized。九成是 Key 没读到。检查TAOTOKEN_API_KEY是否在当前 shell 导出settings.json里写的是环境变量名而不是值。用echo $TAOTOKEN_API_KEY | head -c 8确认前几位。报错二写入后文件被覆盖历史条目消失。检查是不是用了 Write 工具或重定向去写memory/下的文件。除了NOW.md其他记忆文件只能用追加。把allow_overwrite配置核对一遍。报错三INDEX.md里的条目检索不到。先看目标文件是否在.archive/下点号目录会被跳过。再看 frontmatter 的status是不是superseded被取代的条目检索时会跳过。报错四中文查询 0 结果。前面说过FTS5 分词问题。切到query模式或写入时加空格。长期方案是等搜索引擎支持 trigram 或 ICU 分词。报错五夜间反思没跑。检查 cron 表达式和时区。reflection_at 23:45是按timestamp_tz解释的如果服务器是 UTC 而配置写 Asia/Shanghai实际触发时间会偏 8 小时。用date命令确认系统时区。报错六归档后文件还在被索引。确认归档目录名是.archive而不是archive。少了点号搜索引擎照样索引冷热分离就失效了。排障时如果怀疑是通道问题可以直接用模型对话页面手动发一条消息对照排除是配置还是网络的问题模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_system接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_system7. 把记忆系统接进长期编码与 Agent 工作流目录骨架搭好、通道验证通过之后下一步是让它跑起来。日间靠 heartbeat 每 45 分钟巡检一次扫描 session 消息、写日志、轻量去重、刷新NOW.md23:30 做全天日志同步补漏23:45 夜间反思做深度 CRUD 回写把日志里的洞察分类成 lesson、person、decision 写进知识库周日 00:00 跑 GC 把冷数据归档。这套流程里模型调用密集尤其是夜间反思要读多个文件、做比对、生成结构化输出。如果你的 Agent 是长期跑编码任务或需要多轮工具调用用 Coding Plan 会比按次调用更稳配额和并发都更适合这种持续负载Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_system我自己的经验是别一次性把十个目录全建满。从阶段 0 开始NOW.md加AGENTS.md加每日日志三个文件就能跑起基本的跨 session 记忆。第一周加INDEX.md和lessons/、decisions/第二周加 frontmatter 规范和夜间反思第三周再上语义搜索和 GC。每个阶段都能独立运行遇到真实问题再加层比一开始就设计一套完美架构然后卡在配置里强得多。最后提醒一句记忆系统的价值不在目录多漂亮而在写入纪律。追加式、先读再写、冲突不静默覆盖这三条守住了目录结构才有意义。