如果你正在使用 GitHub Copilot 或类似的 AI 编程助手是否曾有过这样的困惑为什么它有时能精准地理解你的意图生成完美的代码有时却又像失忆了一样反复询问你已经定义过的变量或函数或者你是否希望它能记住你整个项目的架构、编码规范甚至是你与它之前的对话历史从而提供更连贯、更个性化的辅助问题的核心在于“上下文”。传统的 AI 助手其“记忆”是短暂且有限的通常只局限于当前打开的文件或最近几次对话。这就像让一个只记得眼前几行字的助手来帮你写一本小说其局限性可想而知。本文将深入探讨一个前沿且实用的解决方案通过AGENTS.md文件注入和“Memory 工具”构建的三层记忆机制来系统性地扩展和优化 AI 编程助手的上下文能力。这不是一个简单的功能开关而是一套工程化的方法论。我们将从 Copilot 等工具的上下文机制原理讲起拆解三层记忆短期、项目级、长期的具体实现并提供从环境配置到代码示例的完整实践指南。读完本文你将能透彻理解AI 编程助手上下文管理的核心瓶颈。亲手搭建一个具备“持久化记忆”能力的智能编程环境。掌握通过AGENTS.md等文件进行“知识注入”的最佳实践。规避在扩展上下文时常见的性能与安全陷阱。1. 这篇文章真正要解决的问题打破 AI 编程助手的“金鱼记忆”AI 编程助手极大地提升了开发效率但其“健忘症”是阻碍其从“好用的工具”进化为“可靠的伙伴”的最大障碍。这种健忘体现在三个层面短期记忆丢失在同一个会话中如果你切换了话题或文件助手可能无法将之前的讨论背景关联到新的任务上。例如你刚解释了数据库表结构紧接着让它写一个查询它可能会问“哪个表”。项目上下文缺失助手无法自动感知你项目的整体结构、技术栈选型、配置文件位置、核心业务逻辑等。每次都需要你手动复制粘贴相关代码片段来“提醒”它过程繁琐且低效。长期经验断层你与助手反复沟通形成的偏好比如“请用 TypeScript 接口而非 any 类型”、“函数命名采用小驼峰”、项目特定的约定、甚至是解决过的历史难题都无法沉淀下来。每次新会话都是一次“从零开始”的磨合。本文提出的AGENTS.md注入 Memory 工具 3 层记忆方案正是为了系统性地解决这三个问题。它不是一个特定产品的功能而是一种设计模式适用于基于大型语言模型的各类编程助手如 GitHub Copilot, Cursor, 以及各类自建的 AI 编码 Agent。AGENTS.md文件充当项目的“说明书”或“知识库”以结构化的文本形式向 AI 助手静态注入项目级的上下文和长期经验。Memory 工具通常指一套程序化的机制可能是本地向量数据库、缓存或简单的文件存储用于动态管理会话中的短期记忆和跨会话的长期记忆。通过将两者结合我们能为 AI 助手构建一个从“瞬间”到“永恒”的完整记忆体系。2. 基础概念与核心原理在深入实操前我们需要厘清几个关键概念理解其背后的工作原理。2.1 AI 编程助手的上下文窗口无论是 Copilot 还是其他基于 GPT 等模型的工具其核心都是一个语言模型。模型在生成下一个词时所能“看到”的文本范围就是其上下文窗口Context Window。例如GPT-4 的上下文窗口可能是 128K tokens。当你编写代码时IDE 插件会将当前文件、相邻标签页、相关文件以及你的注释提示一起编码成 tokens 并发送给模型。模型基于这个有限的上下文窗口来生成建议。窗口之外的任何信息对模型而言都是“未知”的。这就是“健忘”的根本原因——信息不在窗口内。2.2AGENTS.md静态知识注入AGENTS.md是一个约定俗成的文件名也可以是CONTEXT.md,PROJECT_GUIDE.md等其核心思想是将一个 Markdown 文件作为项目的一部分专门用于向 AI 助手描述项目。这个文件会被优先读取并纳入上下文窗口。它的作用类似于给新加入项目的工程师一份《 onboarding 文档 》内容包括但不限于项目概述这是什么项目解决什么问题技术栈使用什么语言、框架、数据库、工具链目录结构src/,config/,tests/分别放什么代码规范命名约定、注释要求、代码风格ESLint/Prettier 规则。核心模式常用的设计模式、工具函数、API 响应格式。注意事项已知的坑、特殊的配置、部署流程。通过将这份文档放在项目根目录或特定位置并在与 AI 助手交互时确保其被包含在上下文中你就能一次性为助手注入大量稳定的背景知识。2.3 Memory 工具动态记忆管理Memory 工具则负责处理更动态、更个性化的记忆。它通常是一个软件层位于你的应用和 AI 模型之间负责记忆的存储、检索和注入。其核心是向量数据库技术。存储将你的对话历史、重要的代码片段、错误解决方案等文本通过嵌入模型Embedding Model转换为高维向量并存储起来。检索当你提出新问题时系统将你的问题也转换为向量然后在向量数据库中搜索与之最相关的历史记忆片段。注入将检索到的相关记忆片段作为附加上下文与你的当前问题一起发送给 AI 模型。这样模型就能“回忆”起之前的相关讨论实现连贯的对话和个性化的辅助。2.4 三层记忆架构结合上述两者我们可以构建一个清晰的三层记忆架构记忆层存储媒介内容生命周期管理方式短期记忆对话上下文 / 临时缓存当前会话中的连续对话、当前编辑的文件内容。会话级由 AI 助手的上下文窗口自动管理。项目级记忆AGENTS.md等项目文档项目结构、技术栈、代码规范、核心逻辑等静态知识。项目级手动创建和维护AGENTS.md文件并确保其被加载。长期记忆Memory 工具 (如向量数据库)跨会话的对话历史、解决过的复杂问题、个人编码偏好。永久/可配置通过 Memory 工具自动存储和检索。三层记忆的关系短期记忆是工作台项目级记忆是蓝图长期记忆是经验库。一个强大的 AI 编程助手需要同时利用这三层记忆来提供最佳辅助。3. 环境准备与前置条件我们将以一个 Node.js TypeScript 的示例项目为基础演示如何实现这套机制。你可以将思路迁移到任何技术栈。基础环境操作系统macOS, Linux 或 WSL (Windows Subsystem for Linux)。原生 Windows 可能在某些工具链上遇到兼容性问题建议使用 WSL2。Node.js版本 18 或更高。推荐使用nvm进行版本管理。包管理器npm或yarn。代码编辑器VS Code。这是大多数 AI 编程助手插件的一线支持环境。Git用于版本控制。AI 相关环境与工具AI 编程助手本文以Cursor编辑器为例因为它对 Agent 和上下文管理有较好的内置支持和扩展性。当然核心概念完全适用于 Copilot 等。Memory 工具实现我们将使用LangChain.js和Chroma一个轻量级开源向量数据库来构建一个简单的记忆系统。你也可以选择Pinecone云服务、Weaviate或Qdrant。OpenAI API 密钥如果你使用 OpenAI 的模型如 GPT-4作为后端。请确保你有可用的 API 密钥并了解相关费用。安装核心依赖在你的项目根目录下初始化项目并安装依赖。# 初始化项目 mkdir ai-coding-agent-demo cd ai-coding-agent-demo npm init -y # 安装 LangChain 和 OpenAI 库 npm install langchain langchain/openai # 安装 Chroma 向量数据库及其 LangChain 集成 npm install chromadb langchain/community # 安装 TypeScript 和类型定义如使用 TS npm install typescript ts-node types/node --save-dev # 创建基础目录 mkdir -p src memory重要提醒处理 API 密钥等敏感信息时务必使用环境变量切勿硬编码在代码中。我们使用dotenv来管理。npm install dotenv在项目根目录创建.env文件OPENAI_API_KEY你的_openai_api_key_here # 其他配置如 Chroma 持久化路径等4. 核心流程拆解构建三层记忆系统整个系统的构建可以分为四个主要步骤我们将逐一拆解。步骤一创建项目级记忆 (AGENTS.md)这是最直接的一步。在项目根目录创建AGENTS.md文件。这份文件的质量直接决定了 AI 助手对项目的理解深度。# 项目智能助手指南 (AGENTS.md) ## 项目概述 - **名称**: AI-Powered Task Manager - **描述**: 一个基于 Node.js Express TypeScript 的智能任务管理后端 API集成 AI 用于自动分类和总结任务。 - **核心目标**: 演示如何为 AI 编程助手构建有效的上下文记忆系统。 ## 技术栈 - **运行时**: Node.js (18) - **语言**: TypeScript - **Web框架**: Express.js - **数据库**: SQLite (开发环境)使用 Prisma ORM - **AI/ML**: OpenAI API, LangChain.js - **向量数据库**: Chroma (用于记忆存储) - **测试**: Jest ## 目录结构说明ai-coding-agent-demo/ ├── src/ │ ├── index.ts # 应用入口 │ ├── agents/ # AI Agent 相关逻辑 │ ├── services/ # 业务服务层 │ ├── controllers/ # API 控制器 │ ├── routes/ # Express 路由 │ └── types/ # TypeScript 类型定义 ├── memory/ # Chroma 向量数据库持久化目录 ├── prisma/ # Prisma 架构和迁移文件 ├── AGENTS.md # 本文件 ├── .env # 环境变量 (切勿提交) └── package.json## 代码规范与约定 1. **命名** - 变量/函数camelCase - 类/类型/接口PascalCase - 常量UPPER_SNAKE_CASE 2. **TypeScript** - 避免使用 any。优先使用 unknown 或定义明确的接口。 - 所有导出的函数和类必须显式声明返回类型。 3. **API 设计** - RESTful 风格。 - 响应统一格式{ success: boolean, data?: T, error?: string } 4. **错误处理** - 使用 try-catch 包裹可能失败的操作。 - 使用自定义错误类并在全局中间件中处理。 ## 核心模式与工具函数 - **数据库操作**: 一律通过 Prisma Client 进行。 - **AI 调用**: 封装在 src/agents/ 目录下使用 LangChain 的 RunnableSequence。 - **记忆检索**: 通过 src/agents/memoryManager.ts 中的 searchMemories 函数。 ## 给 AI 助手的特别提示 - 当你看到关于“任务”、“分类”、“总结”的需求时请联想到本项目是任务管理器并参考 src/types/task.ts 中的接口定义。 - 在编写数据库查询时请使用 Prisma 语法例如 prisma.task.findMany({ where: { ... } })。 - 如果用户要求“记住这个”通常意味着需要调用记忆存储功能。关键点这份文档是写给AI和未来的开发者看的。语言要清晰、结构化并包含 AI 能直接利用的线索如“当你看到...请联想到...”。步骤二实现 Memory 工具长期记忆层我们将创建一个简单的记忆管理器它负责将文本存储到 Chroma 向量数据库并能根据查询检索相关记忆。首先创建src/agents/memoryManager.ts// 文件路径src/agents/memoryManager.ts import { Chroma } from langchain/community/vectorstores/chroma; import { OpenAIEmbeddings } from langchain/openai; import { Document } from langchain/core/documents; export class MemoryManager { private vectorStore: Chroma | null null; private collectionName coding_memories; private embeddings: OpenAIEmbeddings; constructor() { // 初始化嵌入模型用于将文本转换为向量 this.embeddings new OpenAIEmbeddings({ openAIApiKey: process.env.OPENAI_API_KEY, }); } /** * 初始化或连接向量数据库 */ async initialize(): Promisevoid { try { this.vectorStore await Chroma.fromExistingCollection(this.embeddings, { collectionName: this.collectionName, url: http://localhost:8000, // Chroma 默认运行地址 }); console.log(✅ 已连接到现有记忆库。); } catch (error) { // 如果集合不存在则创建新的 console.log(未找到现有记忆库将创建新库。); this.vectorStore await Chroma.fromDocuments( [], // 初始为空文档数组 this.embeddings, { collectionName: this.collectionName, url: http://localhost:8000, } ); console.log(✅ 已创建新的记忆库。); } } /** * 存储一段记忆 * param content 记忆内容 * param metadata 关联的元数据如文件路径、会话ID、类型等 */ async storeMemory(content: string, metadata: Recordstring, any {}): Promisevoid { if (!this.vectorStore) { await this.initialize(); } const doc new Document({ pageContent: content, metadata }); await this.vectorStore.addDocuments([doc]); console.log( 已存储记忆: ${content.substring(0, 50)}...); } /** * 检索与查询相关的记忆 * param query 查询文本 * param k 返回最相关的 k 条记忆 * returns 相关的记忆文档数组 */ async searchMemories(query: string, k: number 3): PromiseDocument[] { if (!this.vectorStore) { await this.initialize(); } const results await this.vectorStore.similaritySearch(query, k); console.log( 为查询${query}检索到 ${results.length} 条相关记忆。); return results; } /** * 获取所有记忆谨慎使用可能数据量大 */ async getAllMemories(): PromiseDocument[] { // 注意Chroma 的 get 方法可能不直接返回所有。 // 这是一个简化示例。生产环境需要分页或使用其他方法。 if (!this.vectorStore) { await this.initialize(); } // 这里使用一个空查询来获取一些文档实际需根据 Chroma API 调整 return await this.vectorStore.similaritySearch(, 100); } }代码解释MemoryManager类封装了与 Chroma 向量数据库的交互。initialize方法尝试连接现有集合不存在则创建。storeMemory将一段文本如对话、代码片段及其元数据来源、时间等存储为向量。searchMemories是核心功能根据查询文本的语义相似度从数据库中找出最相关的历史记忆。步骤三启动 Chroma 向量数据库Chroma 可以以服务模式运行。我们使用 Docker 来快速启动确保已安装 Docker。# 拉取 Chroma 镜像并运行 docker pull chromadb/chroma docker run -d -p 8000:8000 chromadb/chroma运行后Chroma 服务将在http://localhost:8000可用。我们的MemoryManager将连接至此。步骤四集成三层记忆到 AI 工作流这是最关键的一步。我们需要一个“协调器”在用户与 AI 助手交互时动态地组装三层记忆的上下文。创建src/agents/contextOrchestrator.ts// 文件路径src/agents/contextOrchestrator.ts import { MemoryManager } from ./memoryManager; import fs from fs/promises; import path from path; export class ContextOrchestrator { private memoryManager: MemoryManager; private projectContext: string ; constructor() { this.memoryManager new MemoryManager(); } /** * 加载项目级记忆 (AGENTS.md) */ async loadProjectContext(): Promisevoid { try { const agentsPath path.join(process.cwd(), AGENTS.md); this.projectContext await fs.readFile(agentsPath, utf-8); console.log( 已加载项目级上下文 (AGENTS.md)。); } catch (error) { console.warn(⚠️ 无法加载 AGENTS.md 文件项目级上下文将为空。); this.projectContext ; } } /** * 为给定的用户查询和当前代码组装完整的提示上下文。 * param userQuery 用户的问题或指令 * param currentCode 当前编辑器中的代码可选 * param sessionId 当前会话ID用于关联长期记忆 * returns 组装好的、准备发送给AI模型的完整提示 */ async assembleFullContext( userQuery: string, currentCode: string , sessionId: string default ): Promisestring { // 1. 确保项目上下文已加载 if (!this.projectContext) { await this.loadProjectContext(); } // 2. 检索相关的长期记忆 const relevantMemories await this.memoryManager.searchMemories(userQuery); const memoryContext relevantMemories .map(doc [记忆 - ${doc.metadata.source || 未知}]: ${doc.pageContent}) .join(\n); // 3. 组装三层上下文 const fullPrompt # 系统指令与上下文 你是一个智能编程助手请基于以下所有上下文信息来响应用户的请求。 ## 项目级上下文静态知识 ${this.projectContext} ## 相关长期记忆历史经验 ${memoryContext || 暂无相关历史记忆} ## 当前工作区短期记忆 用户当前正在编辑的代码 \\\ ${currentCode} \\\ ## 用户请求 ${userQuery} 请根据以上信息生成最合适的代码或回答。请优先参考项目级上下文和长期记忆中的约定。 ; return fullPrompt; } /** * 将一次有价值的交互存储为长期记忆 */ async storeInteractionAsMemory( query: string, response: string, metadata: Recordstring, any {} ): Promisevoid { const memoryContent 用户问: ${query}\n助手答: ${response}; await this.memoryManager.storeMemory(memoryContent, { type: interaction, timestamp: new Date().toISOString(), ...metadata, }); } }这个协调器做了什么加载静态层读取AGENTS.md文件内容。检索动态层根据用户当前问题从向量数据库中查找语义相关的历史记忆。组装上下文将项目上下文、相关长期记忆、当前代码短期记忆和用户问题按照清晰的格式拼接成一个完整的提示Prompt。记忆沉淀提供方法将高质量的问答对存储到长期记忆中。5. 完整示例与代码实现一个任务分类 AI Agent现在让我们用一个具体的功能来演示三层记忆如何协同工作。我们将创建一个“任务分类 Agent”它能根据任务描述自动分类并且能“记住”我们之前对分类规则的调整。5.1 定义数据结构首先创建任务类型定义。// 文件路径src/types/task.ts export interface Task { id?: number; title: string; description: string; category?: TaskCategory; // AI 自动分类 priority?: low | medium | high; createdAt?: Date; } export type TaskCategory work | personal | shopping | learning | other;5.2 创建分类 Agent这个 Agent 将使用 OpenAI 的 LLM并结合我们的上下文协调器。// 文件路径src/agents/taskCategorizer.ts import { ChatOpenAI } from langchain/openai; import { ContextOrchestrator } from ./contextOrchestrator; import { Task, TaskCategory } from ../types/task; export class TaskCategorizerAgent { private llm: ChatOpenAI; private contextOrchestrator: ContextOrchestrator; constructor() { this.llm new ChatOpenAI({ openAIApiKey: process.env.OPENAI_API_KEY, modelName: gpt-4, // 或 gpt-3.5-turbo temperature: 0.1, // 低温度输出更确定 }); this.contextOrchestrator new ContextOrchestrator(); } /** * 核心方法对任务进行智能分类 */ async categorizeTask(taskDescription: string): Promise{ category: TaskCategory; reasoning: string } { // 1. 组装包含三层记忆的上下文 const userQuery 请将以下任务描述分类到最合适的类别中。类别选项work, personal, shopping, learning, other。\n任务描述${taskDescription}; const fullContext await this.contextOrchestrator.assembleFullContext( userQuery, , // 当前代码非必须 categorize_${Date.now()} ); // 2. 调用 LLM 获取分类和推理 const response await this.llm.invoke(fullContext); // 3. 解析响应 (简单示例实际应用需要更健壮的解析) const responseText response.content.toString(); let category: TaskCategory other; let reasoning 未提供明确推理。; // 简单解析逻辑查找第一个出现的类别词 const categories: TaskCategory[] [work, personal, shopping, learning, other]; for (const cat of categories) { if (responseText.toLowerCase().includes(cat)) { category cat; break; } } // 尝试提取推理部分假设模型以“推理”开头 const reasoningMatch responseText.match(/推理[:]\s*(.)/); if (reasoningMatch) { reasoning reasoningMatch[1].trim(); } // 4. 将这次成功的分类交互存储为长期记忆 await this.contextOrchestrator.storeInteractionAsMemory( 如何分类任务${taskDescription}, 应分类为${category}。推理${reasoning}, { agent: TaskCategorizer, task: taskDescription } ); return { category, reasoning }; } }5.3 创建主程序进行测试创建src/index.ts来运行一个简单的测试。// 文件路径src/index.ts import { TaskCategorizerAgent } from ./agents/taskCategorizer; import * as dotenv from dotenv; // 加载环境变量 dotenv.config(); async function main() { console.log( 启动任务分类 Agent 测试...\n); const categorizer new TaskCategorizerAgent(); const testTasks [ 完成季度财务报告并发送给经理, 去超市买牛奶和鸡蛋, 学习 LangChain 的 Memory 模块, 预约牙医检查, 修复用户登录 API 的 500 错误 ]; for (const taskDesc of testTasks) { console.log( 处理任务: ${taskDesc}); try { const result await categorizer.categorizeTask(taskDesc); console.log( → 分类: ${result.category}); console.log( → 推理: ${result.reasoning}\n); } catch (error) { console.error( ❌ 处理失败: ${error}\n); } } console.log(测试完成。); } main().catch(console.error);6. 运行结果与效果验证6.1 首次运行无长期记忆在运行前确保Chroma 服务已启动 (docker run -d -p 8000:8000 chromadb/chroma)。.env文件已配置OPENAI_API_KEY。已安装所有依赖 (npm install)。运行测试程序npx ts-node src/index.ts预期输出示例 启动任务分类 Agent 测试... 已加载项目级上下文 (AGENTS.md)。 未找到现有记忆库将创建新库。 ✅ 已创建新的记忆库。 处理任务: 完成季度财务报告并发送给经理 为查询请将以下任务描述分类到最合适的类别中...检索到 0 条相关记忆。 已存储记忆: 用户问: 如何分类任务完成季度财务报告并发送给经理... → 分类: work → 推理: 该任务涉及职业相关的职责和汇报属于工作范畴。 处理任务: 去超市买牛奶和鸡蛋 为查询请将以下任务描述分类到最合适的类别中...检索到 0 条相关记忆。 已存储记忆: 用户问: 如何分类任务去超市买牛奶和鸡蛋... → 分类: shopping → 推理: 该任务明确提及购买商品属于购物类别。 ...首次运行分析AGENTS.md被成功加载为 AI 提供了项目背景。由于是首次运行Chroma 中没有任何记忆所以searchMemories返回 0 条结果。AI 完全依靠AGENTS.md和其自身知识进行分类。每次分类后交互都被存储到了长期记忆中。6.2 第二次运行利用长期记忆现在我们修改一下测试加入一个模糊的任务并再次运行。修改src/index.ts中的testTasks数组增加一行const testTasks [ 完成季度财务报告并发送给经理, 去超市买牛奶和鸡蛋, 学习 LangChain 的 Memory 模块, 预约牙医检查, 修复用户登录 API 的 500 错误, 写周报 // 新增一个模糊任务 ];再次运行npx ts-node src/index.ts。预期输出关键变化... 为查询请将以下任务描述分类到最合适的类别中...检索到 5 条相关记忆。 ... 处理任务: 写周报 为查询请将以下任务描述分类到最合适的类别中...检索到 5 条相关记忆。 → 分类: work → 推理: 根据历史记忆类似“完成季度财务报告”的任务被分类为work因此“写周报”也属于工作范畴。效果验证此时searchMemories检索到了之前存储的 5 条记忆。当处理模糊任务“写周报”时AI 的推理中明确提到了“根据历史记忆...”这表明它成功检索并利用了之前的长期记忆“完成季度财务报告”被分类为 work从而做出了更一致、更符合项目历史的判断。这就是三层记忆系统的威力AGENTS.md提供了静态知识基础Memory 工具使得 AI 能够基于历史经验进行决策而当前会话的上下文短期记忆确保了交互的连贯性。7. 常见问题与排查思路在实现和使用此系统时你可能会遇到以下问题问题现象可能原因排查方式解决方案无法加载AGENTS.md文件路径错误、文件名不正确、权限问题。1. 检查process.cwd()输出。2. 确认文件是否存在且可读。3. 在ContextOrchestrator中添加日志打印完整路径。确保文件位于项目根目录或修改loadProjectContext中的路径逻辑。Chroma 连接失败Docker 服务未启动、端口被占用、网络问题。1. 运行docker ps查看 Chroma 容器状态。2. 访问http://localhost:8000/api/v1/heartbeat测试连通性。3. 检查memoryManager.ts中的url配置。确保 Docker 运行端口 8000 空闲。可尝试重启容器docker restart container_id。OpenAI API 调用失败API 密钥无效、额度不足、网络超时。1. 检查.env文件中的OPENAI_API_KEY。2. 查看 OpenAI 账户用量和余额。3. 在代码中捕获并打印详细的错误信息。更新有效的 API 密钥检查网络连接考虑增加超时设置或使用代理合法合规的网络访问方式。记忆检索不相关嵌入模型不合适、查询文本太短、向量数据库未正确索引。1. 检查存储的记忆内容是否完整。2. 尝试不同的嵌入模型如text-embedding-3-small。3. 增加检索数量k。确保存储的记忆文本信息丰富。对于代码记忆可以尝试将代码和自然语言描述一起存储。提示过长导致 API 错误组合后的上下文超出模型令牌限制。1. 计算提示的令牌数可使用tiktoken库。2. 观察 OpenAI API 返回的错误信息。1. 精简AGENTS.md内容。2. 限制检索的记忆条数 (k)。3. 对过长的当前代码进行智能截断如只保留相关函数。分类结果解析错误LLM 输出格式不稳定解析逻辑太简单。1. 打印出 LLM 的完整响应 (responseText)。2. 使用更结构化的输出解析如 LangChain 的OutputFixingParser或StructuredOutputParser。改用 LangChain 的PydanticOutputParser来定义强类型的输出模式让 LLM 返回 JSON。8. 最佳实践与工程建议要将此模式成功应用于生产或严肃的开发环境请遵循以下建议AGENTS.md的精炼与维护保持更新随着项目演进及时更新此文件。可以将其纳入代码审查流程。分而治之对于大型项目可以考虑拆分为多个.md文件如ARCHITECTURE.md,API_GUIDE.md,STYLE_GUIDE.md并在AGENTS.md中做索引。包含示例在文档中直接给出好的和坏的代码示例AI 学习效果更佳。Memory 工具的优化记忆去重在存储前检查是否有高度相似的记忆避免冗余。记忆衰减为记忆添加“权重”或“新鲜度”元数据旧的不重要记忆可以自动清理或降低优先级。分集合存储按类型如“错误解决方案”、“代码模式”、“项目决策”将记忆存储在不同的 Chroma 集合中提高检索精度。本地嵌入模型对于隐私要求高的场景考虑使用xenova/transformers等库在本地运行嵌入模型避免数据出域。安全与成本控制敏感信息绝对不要在AGENTS.md或存储的记忆中包含 API 密钥、密码、内部 IP 等敏感信息。OpenAI API 成本记忆检索本身只涉及廉价的嵌入 API。主要成本来自 LLM 的调用。可以通过缓存常见问题的答案、设置使用频率限制来控制成本。输入审查对用户输入进行基本的审查和清理防止提示注入攻击。与 IDE/编辑器的深度集成自动上下文注入开发 VS Code/Cursor 插件在用户触发 AI 助手时自动调用ContextOrchestrator.assembleFullContext并填充到提示中。一键记忆在 IDE 中添加快捷键将选中的代码片段或当前错误信息快速存储到记忆库。记忆预览在侧边栏展示与当前文件最相关的几条历史记忆。评估与迭代建立评估集准备一组标准问题或编码任务定期测试 AI 助手在有无记忆系统下的表现差异。收集反馈让团队成员标记 AI 回复的“有用/无用”将这些反馈也作为记忆存储用于优化检索和提示。通过AGENTS.md注入和 Memory 工具构建的三层记忆系统你不再是和一个每次会话都失忆的“金鱼”助手合作而是在培养一个逐渐了解你的项目、你的习惯、你的团队规范的“资深搭档”。它记住了你上次是如何解决那个棘手的并发 bug记住了你们团队约定好的代码风格也记住了这个项目为什么选择了 GraphQL 而不是 REST。实现这一系统的技术栈LangChain, Chroma只是工具其核心思想——通过结构化的静态文档和智能化的动态检索来突破上下文窗口的限制——是普适的。你可以将此模式应用于 GitHub Copilot通过自定义指令或插件、Cursor或是任何你正在构建的 AI 编码 Agent 中。下一步你可以尝试将记忆系统与你的代码库索引工具如gpt-engineer,claude-code的上下文管理结合。探索更复杂的记忆检索策略如基于时间、基于来源的混合检索。为不同的开发角色前端、后端、DevOps创建不同的AGENTS.md剖面或记忆集合。技术的最终目的是服务于人。一个好的 AI 编程助手应该让你感觉它就在你的团队里而不是一个每次都需要重新介绍项目的临时工。现在你已经掌握了让它“记住”的关键。 AI编程助手三层记忆系统：AGENTS.md与Memory工具实战指南
如果你正在使用 GitHub Copilot 或类似的 AI 编程助手是否曾有过这样的困惑为什么它有时能精准地理解你的意图生成完美的代码有时却又像失忆了一样反复询问你已经定义过的变量或函数或者你是否希望它能记住你整个项目的架构、编码规范甚至是你与它之前的对话历史从而提供更连贯、更个性化的辅助问题的核心在于“上下文”。传统的 AI 助手其“记忆”是短暂且有限的通常只局限于当前打开的文件或最近几次对话。这就像让一个只记得眼前几行字的助手来帮你写一本小说其局限性可想而知。本文将深入探讨一个前沿且实用的解决方案通过AGENTS.md文件注入和“Memory 工具”构建的三层记忆机制来系统性地扩展和优化 AI 编程助手的上下文能力。这不是一个简单的功能开关而是一套工程化的方法论。我们将从 Copilot 等工具的上下文机制原理讲起拆解三层记忆短期、项目级、长期的具体实现并提供从环境配置到代码示例的完整实践指南。读完本文你将能透彻理解AI 编程助手上下文管理的核心瓶颈。亲手搭建一个具备“持久化记忆”能力的智能编程环境。掌握通过AGENTS.md等文件进行“知识注入”的最佳实践。规避在扩展上下文时常见的性能与安全陷阱。1. 这篇文章真正要解决的问题打破 AI 编程助手的“金鱼记忆”AI 编程助手极大地提升了开发效率但其“健忘症”是阻碍其从“好用的工具”进化为“可靠的伙伴”的最大障碍。这种健忘体现在三个层面短期记忆丢失在同一个会话中如果你切换了话题或文件助手可能无法将之前的讨论背景关联到新的任务上。例如你刚解释了数据库表结构紧接着让它写一个查询它可能会问“哪个表”。项目上下文缺失助手无法自动感知你项目的整体结构、技术栈选型、配置文件位置、核心业务逻辑等。每次都需要你手动复制粘贴相关代码片段来“提醒”它过程繁琐且低效。长期经验断层你与助手反复沟通形成的偏好比如“请用 TypeScript 接口而非 any 类型”、“函数命名采用小驼峰”、项目特定的约定、甚至是解决过的历史难题都无法沉淀下来。每次新会话都是一次“从零开始”的磨合。本文提出的AGENTS.md注入 Memory 工具 3 层记忆方案正是为了系统性地解决这三个问题。它不是一个特定产品的功能而是一种设计模式适用于基于大型语言模型的各类编程助手如 GitHub Copilot, Cursor, 以及各类自建的 AI 编码 Agent。AGENTS.md文件充当项目的“说明书”或“知识库”以结构化的文本形式向 AI 助手静态注入项目级的上下文和长期经验。Memory 工具通常指一套程序化的机制可能是本地向量数据库、缓存或简单的文件存储用于动态管理会话中的短期记忆和跨会话的长期记忆。通过将两者结合我们能为 AI 助手构建一个从“瞬间”到“永恒”的完整记忆体系。2. 基础概念与核心原理在深入实操前我们需要厘清几个关键概念理解其背后的工作原理。2.1 AI 编程助手的上下文窗口无论是 Copilot 还是其他基于 GPT 等模型的工具其核心都是一个语言模型。模型在生成下一个词时所能“看到”的文本范围就是其上下文窗口Context Window。例如GPT-4 的上下文窗口可能是 128K tokens。当你编写代码时IDE 插件会将当前文件、相邻标签页、相关文件以及你的注释提示一起编码成 tokens 并发送给模型。模型基于这个有限的上下文窗口来生成建议。窗口之外的任何信息对模型而言都是“未知”的。这就是“健忘”的根本原因——信息不在窗口内。2.2AGENTS.md静态知识注入AGENTS.md是一个约定俗成的文件名也可以是CONTEXT.md,PROJECT_GUIDE.md等其核心思想是将一个 Markdown 文件作为项目的一部分专门用于向 AI 助手描述项目。这个文件会被优先读取并纳入上下文窗口。它的作用类似于给新加入项目的工程师一份《 onboarding 文档 》内容包括但不限于项目概述这是什么项目解决什么问题技术栈使用什么语言、框架、数据库、工具链目录结构src/,config/,tests/分别放什么代码规范命名约定、注释要求、代码风格ESLint/Prettier 规则。核心模式常用的设计模式、工具函数、API 响应格式。注意事项已知的坑、特殊的配置、部署流程。通过将这份文档放在项目根目录或特定位置并在与 AI 助手交互时确保其被包含在上下文中你就能一次性为助手注入大量稳定的背景知识。2.3 Memory 工具动态记忆管理Memory 工具则负责处理更动态、更个性化的记忆。它通常是一个软件层位于你的应用和 AI 模型之间负责记忆的存储、检索和注入。其核心是向量数据库技术。存储将你的对话历史、重要的代码片段、错误解决方案等文本通过嵌入模型Embedding Model转换为高维向量并存储起来。检索当你提出新问题时系统将你的问题也转换为向量然后在向量数据库中搜索与之最相关的历史记忆片段。注入将检索到的相关记忆片段作为附加上下文与你的当前问题一起发送给 AI 模型。这样模型就能“回忆”起之前的相关讨论实现连贯的对话和个性化的辅助。2.4 三层记忆架构结合上述两者我们可以构建一个清晰的三层记忆架构记忆层存储媒介内容生命周期管理方式短期记忆对话上下文 / 临时缓存当前会话中的连续对话、当前编辑的文件内容。会话级由 AI 助手的上下文窗口自动管理。项目级记忆AGENTS.md等项目文档项目结构、技术栈、代码规范、核心逻辑等静态知识。项目级手动创建和维护AGENTS.md文件并确保其被加载。长期记忆Memory 工具 (如向量数据库)跨会话的对话历史、解决过的复杂问题、个人编码偏好。永久/可配置通过 Memory 工具自动存储和检索。三层记忆的关系短期记忆是工作台项目级记忆是蓝图长期记忆是经验库。一个强大的 AI 编程助手需要同时利用这三层记忆来提供最佳辅助。3. 环境准备与前置条件我们将以一个 Node.js TypeScript 的示例项目为基础演示如何实现这套机制。你可以将思路迁移到任何技术栈。基础环境操作系统macOS, Linux 或 WSL (Windows Subsystem for Linux)。原生 Windows 可能在某些工具链上遇到兼容性问题建议使用 WSL2。Node.js版本 18 或更高。推荐使用nvm进行版本管理。包管理器npm或yarn。代码编辑器VS Code。这是大多数 AI 编程助手插件的一线支持环境。Git用于版本控制。AI 相关环境与工具AI 编程助手本文以Cursor编辑器为例因为它对 Agent 和上下文管理有较好的内置支持和扩展性。当然核心概念完全适用于 Copilot 等。Memory 工具实现我们将使用LangChain.js和Chroma一个轻量级开源向量数据库来构建一个简单的记忆系统。你也可以选择Pinecone云服务、Weaviate或Qdrant。OpenAI API 密钥如果你使用 OpenAI 的模型如 GPT-4作为后端。请确保你有可用的 API 密钥并了解相关费用。安装核心依赖在你的项目根目录下初始化项目并安装依赖。# 初始化项目 mkdir ai-coding-agent-demo cd ai-coding-agent-demo npm init -y # 安装 LangChain 和 OpenAI 库 npm install langchain langchain/openai # 安装 Chroma 向量数据库及其 LangChain 集成 npm install chromadb langchain/community # 安装 TypeScript 和类型定义如使用 TS npm install typescript ts-node types/node --save-dev # 创建基础目录 mkdir -p src memory重要提醒处理 API 密钥等敏感信息时务必使用环境变量切勿硬编码在代码中。我们使用dotenv来管理。npm install dotenv在项目根目录创建.env文件OPENAI_API_KEY你的_openai_api_key_here # 其他配置如 Chroma 持久化路径等4. 核心流程拆解构建三层记忆系统整个系统的构建可以分为四个主要步骤我们将逐一拆解。步骤一创建项目级记忆 (AGENTS.md)这是最直接的一步。在项目根目录创建AGENTS.md文件。这份文件的质量直接决定了 AI 助手对项目的理解深度。# 项目智能助手指南 (AGENTS.md) ## 项目概述 - **名称**: AI-Powered Task Manager - **描述**: 一个基于 Node.js Express TypeScript 的智能任务管理后端 API集成 AI 用于自动分类和总结任务。 - **核心目标**: 演示如何为 AI 编程助手构建有效的上下文记忆系统。 ## 技术栈 - **运行时**: Node.js (18) - **语言**: TypeScript - **Web框架**: Express.js - **数据库**: SQLite (开发环境)使用 Prisma ORM - **AI/ML**: OpenAI API, LangChain.js - **向量数据库**: Chroma (用于记忆存储) - **测试**: Jest ## 目录结构说明ai-coding-agent-demo/ ├── src/ │ ├── index.ts # 应用入口 │ ├── agents/ # AI Agent 相关逻辑 │ ├── services/ # 业务服务层 │ ├── controllers/ # API 控制器 │ ├── routes/ # Express 路由 │ └── types/ # TypeScript 类型定义 ├── memory/ # Chroma 向量数据库持久化目录 ├── prisma/ # Prisma 架构和迁移文件 ├── AGENTS.md # 本文件 ├── .env # 环境变量 (切勿提交) └── package.json## 代码规范与约定 1. **命名** - 变量/函数camelCase - 类/类型/接口PascalCase - 常量UPPER_SNAKE_CASE 2. **TypeScript** - 避免使用 any。优先使用 unknown 或定义明确的接口。 - 所有导出的函数和类必须显式声明返回类型。 3. **API 设计** - RESTful 风格。 - 响应统一格式{ success: boolean, data?: T, error?: string } 4. **错误处理** - 使用 try-catch 包裹可能失败的操作。 - 使用自定义错误类并在全局中间件中处理。 ## 核心模式与工具函数 - **数据库操作**: 一律通过 Prisma Client 进行。 - **AI 调用**: 封装在 src/agents/ 目录下使用 LangChain 的 RunnableSequence。 - **记忆检索**: 通过 src/agents/memoryManager.ts 中的 searchMemories 函数。 ## 给 AI 助手的特别提示 - 当你看到关于“任务”、“分类”、“总结”的需求时请联想到本项目是任务管理器并参考 src/types/task.ts 中的接口定义。 - 在编写数据库查询时请使用 Prisma 语法例如 prisma.task.findMany({ where: { ... } })。 - 如果用户要求“记住这个”通常意味着需要调用记忆存储功能。关键点这份文档是写给AI和未来的开发者看的。语言要清晰、结构化并包含 AI 能直接利用的线索如“当你看到...请联想到...”。步骤二实现 Memory 工具长期记忆层我们将创建一个简单的记忆管理器它负责将文本存储到 Chroma 向量数据库并能根据查询检索相关记忆。首先创建src/agents/memoryManager.ts// 文件路径src/agents/memoryManager.ts import { Chroma } from langchain/community/vectorstores/chroma; import { OpenAIEmbeddings } from langchain/openai; import { Document } from langchain/core/documents; export class MemoryManager { private vectorStore: Chroma | null null; private collectionName coding_memories; private embeddings: OpenAIEmbeddings; constructor() { // 初始化嵌入模型用于将文本转换为向量 this.embeddings new OpenAIEmbeddings({ openAIApiKey: process.env.OPENAI_API_KEY, }); } /** * 初始化或连接向量数据库 */ async initialize(): Promisevoid { try { this.vectorStore await Chroma.fromExistingCollection(this.embeddings, { collectionName: this.collectionName, url: http://localhost:8000, // Chroma 默认运行地址 }); console.log(✅ 已连接到现有记忆库。); } catch (error) { // 如果集合不存在则创建新的 console.log(未找到现有记忆库将创建新库。); this.vectorStore await Chroma.fromDocuments( [], // 初始为空文档数组 this.embeddings, { collectionName: this.collectionName, url: http://localhost:8000, } ); console.log(✅ 已创建新的记忆库。); } } /** * 存储一段记忆 * param content 记忆内容 * param metadata 关联的元数据如文件路径、会话ID、类型等 */ async storeMemory(content: string, metadata: Recordstring, any {}): Promisevoid { if (!this.vectorStore) { await this.initialize(); } const doc new Document({ pageContent: content, metadata }); await this.vectorStore.addDocuments([doc]); console.log( 已存储记忆: ${content.substring(0, 50)}...); } /** * 检索与查询相关的记忆 * param query 查询文本 * param k 返回最相关的 k 条记忆 * returns 相关的记忆文档数组 */ async searchMemories(query: string, k: number 3): PromiseDocument[] { if (!this.vectorStore) { await this.initialize(); } const results await this.vectorStore.similaritySearch(query, k); console.log( 为查询${query}检索到 ${results.length} 条相关记忆。); return results; } /** * 获取所有记忆谨慎使用可能数据量大 */ async getAllMemories(): PromiseDocument[] { // 注意Chroma 的 get 方法可能不直接返回所有。 // 这是一个简化示例。生产环境需要分页或使用其他方法。 if (!this.vectorStore) { await this.initialize(); } // 这里使用一个空查询来获取一些文档实际需根据 Chroma API 调整 return await this.vectorStore.similaritySearch(, 100); } }代码解释MemoryManager类封装了与 Chroma 向量数据库的交互。initialize方法尝试连接现有集合不存在则创建。storeMemory将一段文本如对话、代码片段及其元数据来源、时间等存储为向量。searchMemories是核心功能根据查询文本的语义相似度从数据库中找出最相关的历史记忆。步骤三启动 Chroma 向量数据库Chroma 可以以服务模式运行。我们使用 Docker 来快速启动确保已安装 Docker。# 拉取 Chroma 镜像并运行 docker pull chromadb/chroma docker run -d -p 8000:8000 chromadb/chroma运行后Chroma 服务将在http://localhost:8000可用。我们的MemoryManager将连接至此。步骤四集成三层记忆到 AI 工作流这是最关键的一步。我们需要一个“协调器”在用户与 AI 助手交互时动态地组装三层记忆的上下文。创建src/agents/contextOrchestrator.ts// 文件路径src/agents/contextOrchestrator.ts import { MemoryManager } from ./memoryManager; import fs from fs/promises; import path from path; export class ContextOrchestrator { private memoryManager: MemoryManager; private projectContext: string ; constructor() { this.memoryManager new MemoryManager(); } /** * 加载项目级记忆 (AGENTS.md) */ async loadProjectContext(): Promisevoid { try { const agentsPath path.join(process.cwd(), AGENTS.md); this.projectContext await fs.readFile(agentsPath, utf-8); console.log( 已加载项目级上下文 (AGENTS.md)。); } catch (error) { console.warn(⚠️ 无法加载 AGENTS.md 文件项目级上下文将为空。); this.projectContext ; } } /** * 为给定的用户查询和当前代码组装完整的提示上下文。 * param userQuery 用户的问题或指令 * param currentCode 当前编辑器中的代码可选 * param sessionId 当前会话ID用于关联长期记忆 * returns 组装好的、准备发送给AI模型的完整提示 */ async assembleFullContext( userQuery: string, currentCode: string , sessionId: string default ): Promisestring { // 1. 确保项目上下文已加载 if (!this.projectContext) { await this.loadProjectContext(); } // 2. 检索相关的长期记忆 const relevantMemories await this.memoryManager.searchMemories(userQuery); const memoryContext relevantMemories .map(doc [记忆 - ${doc.metadata.source || 未知}]: ${doc.pageContent}) .join(\n); // 3. 组装三层上下文 const fullPrompt # 系统指令与上下文 你是一个智能编程助手请基于以下所有上下文信息来响应用户的请求。 ## 项目级上下文静态知识 ${this.projectContext} ## 相关长期记忆历史经验 ${memoryContext || 暂无相关历史记忆} ## 当前工作区短期记忆 用户当前正在编辑的代码 \\\ ${currentCode} \\\ ## 用户请求 ${userQuery} 请根据以上信息生成最合适的代码或回答。请优先参考项目级上下文和长期记忆中的约定。 ; return fullPrompt; } /** * 将一次有价值的交互存储为长期记忆 */ async storeInteractionAsMemory( query: string, response: string, metadata: Recordstring, any {} ): Promisevoid { const memoryContent 用户问: ${query}\n助手答: ${response}; await this.memoryManager.storeMemory(memoryContent, { type: interaction, timestamp: new Date().toISOString(), ...metadata, }); } }这个协调器做了什么加载静态层读取AGENTS.md文件内容。检索动态层根据用户当前问题从向量数据库中查找语义相关的历史记忆。组装上下文将项目上下文、相关长期记忆、当前代码短期记忆和用户问题按照清晰的格式拼接成一个完整的提示Prompt。记忆沉淀提供方法将高质量的问答对存储到长期记忆中。5. 完整示例与代码实现一个任务分类 AI Agent现在让我们用一个具体的功能来演示三层记忆如何协同工作。我们将创建一个“任务分类 Agent”它能根据任务描述自动分类并且能“记住”我们之前对分类规则的调整。5.1 定义数据结构首先创建任务类型定义。// 文件路径src/types/task.ts export interface Task { id?: number; title: string; description: string; category?: TaskCategory; // AI 自动分类 priority?: low | medium | high; createdAt?: Date; } export type TaskCategory work | personal | shopping | learning | other;5.2 创建分类 Agent这个 Agent 将使用 OpenAI 的 LLM并结合我们的上下文协调器。// 文件路径src/agents/taskCategorizer.ts import { ChatOpenAI } from langchain/openai; import { ContextOrchestrator } from ./contextOrchestrator; import { Task, TaskCategory } from ../types/task; export class TaskCategorizerAgent { private llm: ChatOpenAI; private contextOrchestrator: ContextOrchestrator; constructor() { this.llm new ChatOpenAI({ openAIApiKey: process.env.OPENAI_API_KEY, modelName: gpt-4, // 或 gpt-3.5-turbo temperature: 0.1, // 低温度输出更确定 }); this.contextOrchestrator new ContextOrchestrator(); } /** * 核心方法对任务进行智能分类 */ async categorizeTask(taskDescription: string): Promise{ category: TaskCategory; reasoning: string } { // 1. 组装包含三层记忆的上下文 const userQuery 请将以下任务描述分类到最合适的类别中。类别选项work, personal, shopping, learning, other。\n任务描述${taskDescription}; const fullContext await this.contextOrchestrator.assembleFullContext( userQuery, , // 当前代码非必须 categorize_${Date.now()} ); // 2. 调用 LLM 获取分类和推理 const response await this.llm.invoke(fullContext); // 3. 解析响应 (简单示例实际应用需要更健壮的解析) const responseText response.content.toString(); let category: TaskCategory other; let reasoning 未提供明确推理。; // 简单解析逻辑查找第一个出现的类别词 const categories: TaskCategory[] [work, personal, shopping, learning, other]; for (const cat of categories) { if (responseText.toLowerCase().includes(cat)) { category cat; break; } } // 尝试提取推理部分假设模型以“推理”开头 const reasoningMatch responseText.match(/推理[:]\s*(.)/); if (reasoningMatch) { reasoning reasoningMatch[1].trim(); } // 4. 将这次成功的分类交互存储为长期记忆 await this.contextOrchestrator.storeInteractionAsMemory( 如何分类任务${taskDescription}, 应分类为${category}。推理${reasoning}, { agent: TaskCategorizer, task: taskDescription } ); return { category, reasoning }; } }5.3 创建主程序进行测试创建src/index.ts来运行一个简单的测试。// 文件路径src/index.ts import { TaskCategorizerAgent } from ./agents/taskCategorizer; import * as dotenv from dotenv; // 加载环境变量 dotenv.config(); async function main() { console.log( 启动任务分类 Agent 测试...\n); const categorizer new TaskCategorizerAgent(); const testTasks [ 完成季度财务报告并发送给经理, 去超市买牛奶和鸡蛋, 学习 LangChain 的 Memory 模块, 预约牙医检查, 修复用户登录 API 的 500 错误 ]; for (const taskDesc of testTasks) { console.log( 处理任务: ${taskDesc}); try { const result await categorizer.categorizeTask(taskDesc); console.log( → 分类: ${result.category}); console.log( → 推理: ${result.reasoning}\n); } catch (error) { console.error( ❌ 处理失败: ${error}\n); } } console.log(测试完成。); } main().catch(console.error);6. 运行结果与效果验证6.1 首次运行无长期记忆在运行前确保Chroma 服务已启动 (docker run -d -p 8000:8000 chromadb/chroma)。.env文件已配置OPENAI_API_KEY。已安装所有依赖 (npm install)。运行测试程序npx ts-node src/index.ts预期输出示例 启动任务分类 Agent 测试... 已加载项目级上下文 (AGENTS.md)。 未找到现有记忆库将创建新库。 ✅ 已创建新的记忆库。 处理任务: 完成季度财务报告并发送给经理 为查询请将以下任务描述分类到最合适的类别中...检索到 0 条相关记忆。 已存储记忆: 用户问: 如何分类任务完成季度财务报告并发送给经理... → 分类: work → 推理: 该任务涉及职业相关的职责和汇报属于工作范畴。 处理任务: 去超市买牛奶和鸡蛋 为查询请将以下任务描述分类到最合适的类别中...检索到 0 条相关记忆。 已存储记忆: 用户问: 如何分类任务去超市买牛奶和鸡蛋... → 分类: shopping → 推理: 该任务明确提及购买商品属于购物类别。 ...首次运行分析AGENTS.md被成功加载为 AI 提供了项目背景。由于是首次运行Chroma 中没有任何记忆所以searchMemories返回 0 条结果。AI 完全依靠AGENTS.md和其自身知识进行分类。每次分类后交互都被存储到了长期记忆中。6.2 第二次运行利用长期记忆现在我们修改一下测试加入一个模糊的任务并再次运行。修改src/index.ts中的testTasks数组增加一行const testTasks [ 完成季度财务报告并发送给经理, 去超市买牛奶和鸡蛋, 学习 LangChain 的 Memory 模块, 预约牙医检查, 修复用户登录 API 的 500 错误, 写周报 // 新增一个模糊任务 ];再次运行npx ts-node src/index.ts。预期输出关键变化... 为查询请将以下任务描述分类到最合适的类别中...检索到 5 条相关记忆。 ... 处理任务: 写周报 为查询请将以下任务描述分类到最合适的类别中...检索到 5 条相关记忆。 → 分类: work → 推理: 根据历史记忆类似“完成季度财务报告”的任务被分类为work因此“写周报”也属于工作范畴。效果验证此时searchMemories检索到了之前存储的 5 条记忆。当处理模糊任务“写周报”时AI 的推理中明确提到了“根据历史记忆...”这表明它成功检索并利用了之前的长期记忆“完成季度财务报告”被分类为 work从而做出了更一致、更符合项目历史的判断。这就是三层记忆系统的威力AGENTS.md提供了静态知识基础Memory 工具使得 AI 能够基于历史经验进行决策而当前会话的上下文短期记忆确保了交互的连贯性。7. 常见问题与排查思路在实现和使用此系统时你可能会遇到以下问题问题现象可能原因排查方式解决方案无法加载AGENTS.md文件路径错误、文件名不正确、权限问题。1. 检查process.cwd()输出。2. 确认文件是否存在且可读。3. 在ContextOrchestrator中添加日志打印完整路径。确保文件位于项目根目录或修改loadProjectContext中的路径逻辑。Chroma 连接失败Docker 服务未启动、端口被占用、网络问题。1. 运行docker ps查看 Chroma 容器状态。2. 访问http://localhost:8000/api/v1/heartbeat测试连通性。3. 检查memoryManager.ts中的url配置。确保 Docker 运行端口 8000 空闲。可尝试重启容器docker restart container_id。OpenAI API 调用失败API 密钥无效、额度不足、网络超时。1. 检查.env文件中的OPENAI_API_KEY。2. 查看 OpenAI 账户用量和余额。3. 在代码中捕获并打印详细的错误信息。更新有效的 API 密钥检查网络连接考虑增加超时设置或使用代理合法合规的网络访问方式。记忆检索不相关嵌入模型不合适、查询文本太短、向量数据库未正确索引。1. 检查存储的记忆内容是否完整。2. 尝试不同的嵌入模型如text-embedding-3-small。3. 增加检索数量k。确保存储的记忆文本信息丰富。对于代码记忆可以尝试将代码和自然语言描述一起存储。提示过长导致 API 错误组合后的上下文超出模型令牌限制。1. 计算提示的令牌数可使用tiktoken库。2. 观察 OpenAI API 返回的错误信息。1. 精简AGENTS.md内容。2. 限制检索的记忆条数 (k)。3. 对过长的当前代码进行智能截断如只保留相关函数。分类结果解析错误LLM 输出格式不稳定解析逻辑太简单。1. 打印出 LLM 的完整响应 (responseText)。2. 使用更结构化的输出解析如 LangChain 的OutputFixingParser或StructuredOutputParser。改用 LangChain 的PydanticOutputParser来定义强类型的输出模式让 LLM 返回 JSON。8. 最佳实践与工程建议要将此模式成功应用于生产或严肃的开发环境请遵循以下建议AGENTS.md的精炼与维护保持更新随着项目演进及时更新此文件。可以将其纳入代码审查流程。分而治之对于大型项目可以考虑拆分为多个.md文件如ARCHITECTURE.md,API_GUIDE.md,STYLE_GUIDE.md并在AGENTS.md中做索引。包含示例在文档中直接给出好的和坏的代码示例AI 学习效果更佳。Memory 工具的优化记忆去重在存储前检查是否有高度相似的记忆避免冗余。记忆衰减为记忆添加“权重”或“新鲜度”元数据旧的不重要记忆可以自动清理或降低优先级。分集合存储按类型如“错误解决方案”、“代码模式”、“项目决策”将记忆存储在不同的 Chroma 集合中提高检索精度。本地嵌入模型对于隐私要求高的场景考虑使用xenova/transformers等库在本地运行嵌入模型避免数据出域。安全与成本控制敏感信息绝对不要在AGENTS.md或存储的记忆中包含 API 密钥、密码、内部 IP 等敏感信息。OpenAI API 成本记忆检索本身只涉及廉价的嵌入 API。主要成本来自 LLM 的调用。可以通过缓存常见问题的答案、设置使用频率限制来控制成本。输入审查对用户输入进行基本的审查和清理防止提示注入攻击。与 IDE/编辑器的深度集成自动上下文注入开发 VS Code/Cursor 插件在用户触发 AI 助手时自动调用ContextOrchestrator.assembleFullContext并填充到提示中。一键记忆在 IDE 中添加快捷键将选中的代码片段或当前错误信息快速存储到记忆库。记忆预览在侧边栏展示与当前文件最相关的几条历史记忆。评估与迭代建立评估集准备一组标准问题或编码任务定期测试 AI 助手在有无记忆系统下的表现差异。收集反馈让团队成员标记 AI 回复的“有用/无用”将这些反馈也作为记忆存储用于优化检索和提示。通过AGENTS.md注入和 Memory 工具构建的三层记忆系统你不再是和一个每次会话都失忆的“金鱼”助手合作而是在培养一个逐渐了解你的项目、你的习惯、你的团队规范的“资深搭档”。它记住了你上次是如何解决那个棘手的并发 bug记住了你们团队约定好的代码风格也记住了这个项目为什么选择了 GraphQL 而不是 REST。实现这一系统的技术栈LangChain, Chroma只是工具其核心思想——通过结构化的静态文档和智能化的动态检索来突破上下文窗口的限制——是普适的。你可以将此模式应用于 GitHub Copilot通过自定义指令或插件、Cursor或是任何你正在构建的 AI 编码 Agent 中。下一步你可以尝试将记忆系统与你的代码库索引工具如gpt-engineer,claude-code的上下文管理结合。探索更复杂的记忆检索策略如基于时间、基于来源的混合检索。为不同的开发角色前端、后端、DevOps创建不同的AGENTS.md剖面或记忆集合。技术的最终目的是服务于人。一个好的 AI 编程助手应该让你感觉它就在你的团队里而不是一个每次都需要重新介绍项目的临时工。现在你已经掌握了让它“记住”的关键。