AI编程代理稳定落地：记忆、代码地图与Token成本治理

我没有想到，真正让 AI 编程代理在项目里稳定干活的最大障碍，不是模型能力，而是"记性"。具体来说，是三种混乱：它记不住上一个会话里刚敲定的技术决策；它看不懂仓库结构，只能靠翻目录树瞎猜；每次这样瞎折腾，token 就哗哗地流走。为了根治这三件事，我花了一两个月写了一套开源的 AI 编程代理工具链，从记忆、代码地图到 token 记账一共拆成 9 个仓库，全部以 MIT 许可发布。这篇就聊聊我为什么这么拆、每个模块解决什么问题、以及实现里真正值得注意的细节。

如果你也在用 AI 编程代理做日常开发，或者在团队里维护一套内部智能编码基础设施，这篇文章应该能帮你少走不少弯路。我不打算给你讲一个"开箱即用"的童话，而是把架构决策和踩坑过程都摊开来说。

1. 三个让我坐不住的问题：记忆断片、盲人摸象、成本失控

1.1 会话断片：AI 永远在重新认识我的项目

我在一个中等规模的项目里同时维护后台服务和一套内部工具库。AI 编程代理刚接入时体验很好，但每开一个新会话，它就会"失忆"。有一次我在上个会话里确定了错误处理必须统一返回 code + message 结构，结果两天后新会话里，它又给我写了一套抛异常的老写法。

当时我的第一反应是换更大的上下文窗口，但很快就发现这条路走不通：会话时间越长，历史内容越占上下文，真正有用的项目约定反而被淹没了。把项目约定写进每个 prompt 也不是办法，因为约定本身是动态的，今天定的决策明天可能就被推翻了。

本质上，这是把"长期记忆"错误地压在了"短期上下文"里。模型上下文窗口再大，也不该承担跨会话的知识管理职责。我需要一个外置的记忆层，把项目决策、环境约定、用户偏好结构化成可检索的数据，而不是让代理每次从头推断。

1.2 盲人摸象：代理看不懂仓库结构

第二个问题是代码地图缺失。早期我图省事，让代理自己去仓库里翻文件。小仓库还行，一旦模块数量超过两百，它就开始漏细节，经常在 docs 目录里翻到一段过时说明，当真当成最新规范来执行。

最浪费的是，它每进入一个新会话都要重新遍历目录树，猜测哪些文件相关。这个过程本身就在消耗大量 token，而且准确性不高。它不知道这个仓库的入口在哪里，不知道模块之间的依赖关系，更不知道"改 A 文件会影响哪些模块"。

后来我想明白，代理不该在运行时去"画地图"，而是应该有一张预先计算好的结构化地图，直接告诉它模块边界、符号位置、依赖关系和测试映射。这和人类开发者看仓库的方式是一样的：你不会从根目录一层层翻代码，而是先看入口、看文档、看目录结构。

1.3 成本失控：token 成了一把糊涂账

第三个问题其实是被前两个问题放大的。代理翻文件、重复读上下文、失效重试，每一件都在烧 token。我有段时间跑批处理任务，为了减少失败开了自动重试，月底看到账单才发现，大量成本来自重试和上下文的重复计数。

更麻烦的是，多个会话并行跑的时候，我根本没法说清楚每个任务的成本。某个实验性 prompt 到底花了多少钱？哪个模型最烧钱？这些问题完全没有答案。单次调用看单价不贵，累积起来才吓人，等你发现的时候，预算已经超了。

我需要的是一个埋点层：每次 LLM 调用都被记录，按任务、会话、项目维度归类，并且能在预算撞线之前叫停。这听起来像基础设施建设，但少了它，AI 编程代理在真实项目里根本没法规模落地。

1.4 为什么我不做一个"全家桶"工具

这三个问题其实不在同一个层面：记忆管的是长期状态，代码地图管的是静态结构，token 记账管的是运行成本。硬塞进一个工具里，最后一定哪个都不好用。

所以在设计初期，我就决定把它们拆开。这也是整套系统最终拆成 9 个仓库的起点：每个模块可以被独立使用、独立部署、独立替换，组合起来又是一条完整工具链。

2. 九个仓库的模块边界与架构逻辑

2.1 先给模块分三层

整条工具链我分成三层：内核层、上下文层、计量层。

内核层负责定义协议和公共数据结构，包括事件格式、配置 schema、仓库间的通信契约。上下文层承载两个大的子系统：记忆和代码地图，它们解决的是"代理怎么理解项目和历史"的问题。计量层负责 token 的采集、聚合、配额和告警，解决的是"代理花了我多少钱"的问题。

三层是单向依赖的：内核层不依赖任何上层服务，上下文层不依赖计量层，计量层也不反向依赖上下文层。这样好处很明显，你哪怕只想要 token 审计，也能单独把计量层拿出来用，不用拖上整套系统。

2.2 九个仓库分别负责什么

这里我用的是我仓库里的实际代号，名字不重要，关键是模块边界。九个子项目可以归到三层里看：

乍一看 9 个仓库很多，但每个仓库的代码量都不大，核心是边界要清晰。比如 memokit-roller 只做"抽取和压缩"这一件事，它不关心数据怎么存，也不关心检索怎么打分，这些分别由 store 和检索模块负责。

2.3 为什么坚持拆开而不是打成一个大仓库

如果有人想从零做这套东西，我建议也先拆清楚再动手。拆开带来的直接收益是部署维度解耦：代码地图索引器偏重 CPU，跑的时候可以单独给资源；记忆服务偏重 IO，适合常驻后台；记账服务偏重吞吐，但单机也能扛。三者混在一起，你没法针对性地扩某一个。

另外一个原因是失败域隔离。索引器如果因为某个仓库文件太怪崩溃了，不应该影响正在进行的 token 计量。拆成独立进程之后，单个模块挂掉、重启，对整体影响都是可控的。

第三个原因比较现实：MIT 许可下，仓库边界就是复用边界。别人可能只想拿 memokit-store 当个记忆库，或者只拿 codemap-indexer 做代码检索。你要是把所有东西揉成一个仓库，他们就必须接受整套架构的包袱。

3. 记忆子系统：让代理从"七秒记忆"变成"项目老兵"

3.1 把记忆分成三类，而不是一个巨大的文本堆放场

我最早犯过的一个错误，是试图把历史对话全部存下来，做成一个超大笔记。结果检索效果很差，因为里面 80% 都是噪音。后来我把记忆分成三类：

• 事实记忆：项目的技术栈、目录约定、部署方式，比如"项目使用 Python 3.11 和 uv 管理依赖"。
• 决策记忆：过去明确拍板过的技术选择，比如"API 路由走 REST 风格，不引入 GraphQL"。
• 流程记忆：做事习惯和操作流程，比如"提交前必须先跑格式化器和测试套件"。

这三类记忆的更新频率和重要程度完全不同。事实记忆相对稳定，决策记忆是越久越值得保留，流程记忆则需要随着项目演进持续修正。分类之后，我在存储和检索上都可以区别对待，而不是一锅炖。

一条标准的记忆记录长这样：

{ "id": "mem_0a1f2b", "type": "decision", "content": "用户登录链路统一使用 access_token + refresh_token 双令牌方案", "source_session": "sess_8c001", "created_at": "2025-06-14T10:22:00Z", "importance": 0.92, "confirmed": true, "tags": ["auth", "api-design"] }

importance 是一个置信度评分，负责控制这条记忆在检索结果里的权重。confirmed 字段表示是否经过了人工确认或者后续对话的反复验证，没确认的记忆权重会被降低。

3.2 摄取管道：不是所有对话都值得记

记忆从哪来？最直接来源是代理自己的会话日志。代理和人的交互一般都有 JSONL 日志，包含用户请求、代理调用工具的结果、最终代码变更。memokit-roller 做的就是读取这些日志，做三件事：清洗、抽取、压缩。

清洗是去掉机械重复内容，比如代理每轮都重新输出一次文件路径列表，这种信息没有长期价值。抽取是让模型判断当前对话里有没有"值得记住的东西"，判断标准可以是：是否推翻了之前的约定，是否引入了新的技术方案，是否表达了用户的长期偏好。压缩是把同一主题的零散记录滚动合并成摘要，避免记忆库无限膨胀。

这里我做了个比较重要的设计：抽取不追求全量覆盖，宁可漏掉一些，也不要把噪音存进来。漏掉一条记忆顶多是代理之后多问一句，存错一条记忆则会导致它在后续会话里长期带着错误假设往前走，危害大得多。

3.3 检索策略：关键词、向量、时间衰减三路混合

有了分类和存储，更关键的是怎么把对的记忆捞出来。我只试过纯向量检索，效果很差，因为项目里的术语和代码符号往往具有很强的精确匹配性质，语义检索容易把"用户认证"和"用户注册"混在一起。

最后我用的方案是三路混合召回：

• 关键词路：按符号名、文件路径、标签做精确匹配，解决"找某个具体函数或配置"这类需求。
• 向量路：按语义相似度找相关记忆，解决"项目里有没有人处理过类似故障"这类模糊需求。
• 时间衰减路：对过期记忆降权，三个月前的决策如果没有被再次确认，权重自动下降。

三路结果做加权合并，importance 高的记忆天然排前面。这其实就是经典的混合检索思路，但放到记忆场景里特别合适，因为记忆既有精确属性，又有语义属性，还天然带时间维度。

3.4 存储选型：单机嵌入式数据库先顶上，别急着上分布式

我见过不少团队一上来就上独立向量数据库，其实对大部分日常项目是过度设计。记忆数据的量级，在一个几十人的研发团队里，撑死也就是几十万条级别，单机的嵌入式数据库完全扛得住。

我在 memokit-store 里用的存储方案是本地嵌入式数据库加向量扩展，简单说就是把元数据和向量索引放在同一个文件里。好处是零运维，坏处是水平扩展性有限。真到了要水平扩展的那天，可以把存储层拆出去，但因为 API 边界已经定好，迁移成本是可控的。

顺序很重要：先用最简单的存储把数据模型和检索策略跑通，再去考虑分布式。因为记忆系统的核心难点从来不是存储引擎，而是数据质量这条管道。

4. 代码地图子系统：把仓库结构变成代理能看懂的地图

4.1 思路转变：别让代理在运行时现场翻仓库

代理在仓库里盲找文件，本质上和一个人拿到十万行代码但没有目录说明是一样的体验。与其这样，不如提前把仓库结构变成结构化地图。

地图不是简单的目录树，而是一张包含模块边界、符号位置、依赖关系、入口点和测试映射的索引。代理在使用时只需要查询地图，而不是自己去扫描文件系统。这一步省下的 token 非常可观，因为它避免了代理反复读取无关文件。

4.2 索引器到底做了什么

codemap-indexer 的职责是静态扫描仓库然后生成地图，大致经过这几步：

1. 识别项目类型：根据包管理文件判断语言和构建工具。
2. 解析模块结构：把目录和文件映射成模块树，识别公共 API 和内部实现。
3. 提取符号级信息：通过通用语法解析库获取函数、类、接口、导出符号，以及符号所在文件和行号。
4. 建立依赖关系：记录文件与模块之间的引用与依赖边，产出"改 A 会影响哪些文件"的结果。
5. 识别入口点：区分 CLI 入口、服务启动入口、配置文件、测试入口。

最重要的是第 4 步。很多代码检索工具只做符号定位，不做依赖关系分析，但代理在实际干活时最关心的恰恰是影响范围。哪个文件被谁引用，改了这个函数之后哪些测试需要一起跑，这些信息比"符号在第几行"有用得多。

4.3 地图格式与版本：地图必须跟着提交走

地图的数据格式我用的是二进制序列化，这样体积小、加载快，同时带上 schema_version 和 repo_commit 两个字段。repo_commit 是地图对应的仓库提交哈希，每次构建地图都会记录来源，这样代理就知道自己拿到的地图是哪个代码状态的产物。

如果地图对应的 commit 和当前工作区差得太远，代理应该主动触发一次地图更新，而不是拿着旧地图硬干。这个逻辑看起来简单，但一开始我没做，结果代理拿着三周前的地图去改已经重构过的模块，改出来的内容完全不能用。

4.4 增量更新：文件监听、指纹校验和幽灵条目

地图不能每次全量重建，否则大仓库的构建成本会让人抓狂。codemap-watch 的做法是监听文件系统事件，检测到变更后先计算文件哈希，只有内容真正变化才触发增量重索引。

增量更新最麻烦的是文件重命名和删除。如果只更新变更文件本身，依赖它的模块里可能还留着旧的符号引用，地图里会出现"幽灵条目"。我最终的处理方式是引入失效标记：文件名或符号名发生变化时，先把受影响的旧条目标记为失效，再扫描依赖它的模块，逐条清理引用。宁可让地图更新慢一点，也不能让代理拿到一份带着幽灵引用的地图。

5. token 记账子系统：每一分 token 都要知道去向

5.1 埋点位置：在代理 SDK 里拦截，而不是事后解析日志

token 计量的第一原则是：在调用发生的地方埋点，而不是事后从日志里猜。ctxbridge-sdk 里内置了一个计量客户端，代理每次发起 LLM 请求时，自动生成一条计量记录，包含请求 ID、会话 ID、任务 ID、模型名称、提示词 token 数、生成 token 数、缓存命中 token 数和工具调用次数。

流式响应有个小坑：模型是一个块一个块吐出来的，不能等全部结束才读 usage 字段。我在 SDK 里做的处理是边接收边累计增量，流结束以后用服务端返回的最终 usage 做校准。两者不一致时以服务端为准。

5.2 幂等去重：重试机制差点让我把同一笔请求算了两遍

我第一次跑通计量服务时，发现账单比预期高一截。仔细排查后发现，代理的上游有过一次重试，同一个 prompt 被发送了两次，计量服务把它当成了两笔独立消费。

解法很朴素：每个请求在源头生成唯一的 request_id，计量表里对 request_id 建立唯一约束，重复上报直接丢弃。这个约束救了后期所有类似问题。没有幂等保护的计量系统，在自动重试和断线重连面前完全不可信。

5.3 成本换算：token 数和钱之间隔着一张价目表

token 数不是钱，要换算成成本，必须有模型价目表。我把不同模型的计价配置做成了 YAML 表，按输入、输出、缓存命中三类分别计价。价目表以配置文件维护，模型改价时不用改代码。

这里有个容易被忽略的点：缓存命中的计费规则不同。有些模型对缓存命中 token 收取的费用远低于普通输入。如果统计时把所有 token 都按原价计算，成本会被高估，误导预算决策。所以计量数据里要把 cached_tokens 单独存一个字段，换算成本时单独计价。

5.4 配额预警与熔断：预算撞线之前先叫停

token 记账不能只记不管，否则它只是一个昂贵的监控系统。tokemeter-guard 专门做预算控制，核心是两个阈值：警告阈值和熔断阈值。

比如一个任务池预算是每月 500 万 token，消耗到 80% 时返回告警，让代理提示用户"预算接近上限，建议缩减自动重试次数"。消耗到 100% 时就进入熔断状态，直接阻止新的高成本任务启动，或者强制切换成更便宜的备用模型。熔断策略是可配置的，不是一路硬切，因为有些任务宁可多花钱也不能中断。

5.5 一张示例账单长什么样

聚合维度上，我按项目、会话、任务三层建立分组。这是 tokemeter-api 提供的一张示例查询结果：

看到 task_003 这类结果时，你就能立刻明白为什么之前预算总是不够：一个没开缓存、反复重试的任务，成本几乎顶过其他所有任务之和。

6. 把三块拼起来：接入一个实际 AI 编程代理的完整链路

6.1 三种接入方式，按场景选

整套工具链不强制绑定某一种部署形态，我实际用下来比较顺的有三种方式：

• 本地 sidecar 模式：在代理进程旁边起三个本地服务，通过本地地址调用，延迟低，适合单人开发。
• 独立服务模式：记忆、代码地图、计量作为后端服务部署，多人共享，适合团队使用。
• 纯 SDK 内嵌模式：token 计量的部分可以直接在代理进程内跑，不用起服务，适合只想解决账单问题的人。

代码地图和记忆服务需要常驻进程，纯 SDK 内嵌不太现实，所以我的建议是：单人场景选自部署 sidecar，多人场景选独立服务，token 记账单独抽出来用。

6.2 最小配置长什么样

整套工具链的配置被 agentkit-core 统一管理，下面是一个最小配置文件的示例：

memory: store_url: "local://~/.cache/agentkit/memory.db" embed_model: "local-embedding-model-name" retrieval: top_k: 8 time_decay_days: 90 codemap: indexer_path: "~/.cache/agentkit/codemaps" watch: true language: "auto" metering: enabled: true endpoint: "http://127.0.0.1:8370" budget_pool: "monthly-main" warn_at_percent: 80 hard_limit_percent: 100

配置里的字段都是语义化的，路径、模型名、接口地址按你自己的环境替换就行。关键是三层服务都只需要这一份配置，不需要分别维护。

6.3 代理启动时发生了什么

链路是这样的：代理启动后先向记忆服务请求一份项目 profile，里面包含技术栈、项目约定、近期重要的决策记录。同时向代码地图服务请求模块总览和入口文件列表。这两份信息被压缩成一个精简的上下文块，塞进代理的系统提示里。

会话进行中，代理如果遇到不确定的文件位置，调用代码地图的查询接口而不是自己翻目录。每次 LLM 请求发出时，SDK 自动上报一笔计量记录。消耗接近预算阈值时，代理收到告警并主动降低自动重试频率。

整个链路跑通之后，一个新会话的启动时间会缩短很多，因为代理不需要再去探索仓库，直接凭着地图和记忆进入干活状态。

6.4 性能与可靠性约束

这三块服务本身的性能不能成为新的瓶颈，我自己定的约束是：记忆检索单次延迟在 50 毫秒以内，代码地图查询走内存缓存，计量上报走异步批量通道，绝不在代理的主路径上做同步等待。

记忆写入和地图索引都可以放到后台排队，甚至跑成定时任务。只有检索和查询要走同步路径，因为代理在等结果。异步处理所有脏活累活，同步处理必须的读取，这一条对任何 AI 基础设施都适用。

7. 全 MIT 的决策过程，以及我刻意没做的事

7.1 为什么是 MIT，而不是别的许可证

选择 MIT 几乎没怎么犹豫。我偏向让这套工具链尽量被广泛使用，包括被商业项目直接集成。MIT 许可是所有宽松许可证里文字最少、理解成本最低的，对采用者几乎没有心理门槛。

有人问过为什么不用 AGPL，毕竟也能开源。我的看法是：AGPL 会天然地把一部分不想开源的公司挡在门外，而我的目标恰恰是让想用的人都能用。对独立开发者来说，没有法务团队去解释许可证边界，最稳妥的策略就是选择最宽松的形式，让别人完全不用纠结。

7.2 我刻意没做的事

这套系统做了很多，但我也刻意压住了一些膨胀冲动。第一个是没做托管 SaaS 一键部署，因为维护多租户服务会吞掉我所有精力，而且本地部署的价值更大。第二个是没绑定任何模型厂商，记忆里的 embedding、代码地图的索引、token 计价的价目表全部抽象成接口，用户可以换模型厂商或自建推理服务，不影响上层。

第三个是没做复杂的管理界面。这不是偷懒，而是想把基础设施的边界留在 API 层。界面是主观的，每个人想要的展示方式都不同，但数据结构和服务接口是客观的，按约定暴露清楚就够了。社区里已经有人基于计量 API 做了自己的成本面板，我反而觉得这是最好的结果。

7.3 对普通开发者的价值：每个仓库都可以单独拿走

MIT 的另一个好处是复用边界清晰。你现在就可以只拿 memokit-store 当个人笔记库，或者只拿 codemap-indexer 做现有工具的代码检索插件，又或者只把 tokemeter-api 接到自己的脚本体系里做 token 审计。9 个仓库之间虽然默认搭配工作，但没有任何一个仓库强迫你接受整套生态。

8. 开发与使用中踩过的坑，以及下一步打算

8.1 记忆系统的假阳性：把临时噪音当成了事实

第一次跑通记忆抽取时，效果很惊艳，但很快发现它会把很多临时内容当成事实存下来。比如有一次我在对话里随口说"这个方案可以以后再考虑"，结果被记录成了一条决策记忆，几天后代理还真的引用这条"决策"来建议方案。

后来我加了三道过滤，效果立竿见影：显著性评分只保留高分内容；新记忆默认带未确认标签，权重自动打折扣；每隔一段时间做一次回顾确认，只有被多次相关对话印证过的记忆才提升重要性分数。现在假阳性的比例已经降到了可以接受的水平。

8.2 代码地图的幽灵引用：重命名文件后代理还在找旧符号

增量更新上线以后，我遇到一个经典问题：某个模块的文件被重命名，旧文件名在文件系统里消失了，但地图里依赖它的模块仍然保留了旧符号引用。代理按地图找到文件路径，一打开发现不存在，整个任务直接卡在困惑状态。

解决办法是引入失效标记加依赖重扫，前面也提过。每次检测到文件重命名或删除，先不急着删除旧条目，而是把旧条目标记为失效，然后重新扫描依赖它的模块，把所有引用旧符号的边一并处理掉。做完这一层清理之后，幽灵引用基本清零。

8.3 token 计量的精度：重试去重和流式累计缺一不可

计量的坑主要集中在两个地方。一个是重试导致重复计费，这个用 request_id 唯一约束解决了。另一个是流式响应的 token 统计，刚开始我只取最后一个 chunk 的 usage 字段，后来发现某些流式接口只有在完整结束时才会带 usage，中间 cumulative 值和最终值还会对不上，最终统一以服务端最终回包为准。

另外我还加了对账任务，每天跑一次，将 SDK 上报的计量数据和采购账单做比对。一旦发现偏差超过阈值，先降级为"估算模式"，避免把错误的精确数字展示给用户。

8.4 下一步打算：我会继续把这三块打磨到真正省心的程度

这套系统我用了几个月，最大的感受是：AI 编程代理本身的能力已经够用了，缺的是让它稳定落地的外围设施。记忆、代码地图、token 记账这三件事，本质上是在给代理补上"项目经验"和"成本意识"。

我接下来的计划比较务实：给记忆服务做更好的冲突检测，当两条记忆内容矛盾时，不再简单取新的，而是把矛盾本身记录下来；给代码地图增加更细的调用链分析，让代理能回答"这个接口被哪些调用方依赖"之类的问题；给 token 记账增加更灵活的任务级预算模板。这三件事都是基于实际使用中的反馈，不会去加什么炫技功能。

最后再分享一个我做这个项目以来最实用的小技巧：不要等整套系统完整了再开始接入代理。先把 token 记账跑起来，你很快就会对"代理的每一次动作到底要花多少钱"有直观体感，连带着会主动去调上下文压缩和地图查询的频率。成本可见性是所有优化步骤里回报最快的一步。