1. 项目概述一个能记住一切的智能对话伙伴如果你和我一样经常和ChatGPT这类大模型打交道肯定遇到过两个头疼的问题一是对话聊着聊着它就“失忆”了记不住我们之前讨论过的长篇文档细节二是每次想让它基于我自己的资料库比如一堆PDF、网页、视频文稿来回答问题都得把整个文档重新贴给它不仅麻烦而且很快就会触及模型的上下文长度限制成本也高得吓人。Memory Bot 这个项目就是为解决这些痛点而生的。它本质上是一个运行在Node.js环境下的命令行聊天机器人但它的核心能力在于“记忆”。它通过结合向量数据库和LangChain框架实现了两个关键功能无限长的上下文支持和完整的对话历史记忆。你可以把它看作是一个永远在线、且过目不忘的私人AI助理无论是分析你上传的百页PDF还是回顾几个月前的某次技术讨论它都能精准地调取相关信息给出基于上下文的回答。这个工具特别适合需要深度处理私有文档的开发者、内容创作者、研究人员或任何知识工作者。比如你可以用它来基于文档的问答上传公司年报、技术手册、研究论文然后直接提问“2023年Q3的毛利率是多少”或“请总结第五章的核心论点”。内容创作辅助喂给它你的品牌指南、过往的营销文案让它生成风格统一的新内容。学习与研究导入某个YouTube技术讲座的转录稿或一系列博客文章让它帮你梳理知识脉络、解答疑问。它的魔力不在于模型本身它调用的是OpenAI的API而在于其精巧的“记忆”架构设计。接下来我们就深入拆解这套设计并手把手带你从零部署、配置到高效使用。2. 核心架构与设计思路拆解Memory Bot 的聪明之处在于它没有笨拙地把所有资料都塞进每次对话的提示词Prompt里而是采用了“外部记忆库动态检索”的策略。理解这个架构是用好它的关键。2.1 三层记忆系统短期、长期与上下文你可以把Memory Bot的记忆系统想象成人的记忆机制短期记忆窗口缓冲记忆这是最基础的一层由LangChain的ConversationBufferWindowMemory实现。它就像一个滑动窗口只保留最近几次可配置的对话轮次。它的作用是让AI能理解当前对话的即时语境进行连贯的交互。你可以通过/wm命令随时关闭它比如在进行一次性问答时避免无关的历史对话干扰。长期记忆向量存储记忆这是项目的核心创新点之一。所有历史上的对话包括用户的提问和AI的回答都会被转换成向量Embeddings存储在一个专门的HNSWLib向量索引中。当你提出新问题时系统会从这个“记忆库”里检索出与当前问题最相关的几段历史对话作为背景信息喂给AI。这意味着即使对话发生在几天前只要内容相关AI就能“回想”起来。这通过/mc命令控制检索数量。上下文记忆向量存储上下文这是另一个核心向量库独立于对话记忆。你上传的所有外部文档PDF、网页、视频转录稿等都会被处理并存储在这里。当你的问题涉及这些文档内容时系统会从这里检索出最相关的文档片段。这实现了“无限上下文”因为实际发送给API的只是最相关的几个片段而非整个文档。这通过/cc命令控制。关键理解/mc调取的是“我们之前聊过什么”而/cc调取的是“你给我的资料里写了什么”。两者结合让AI既能引经据典又能温故知新。2.2 工作流程与成本控制逻辑整个系统的运行流程清晰地体现了其成本控制的考量用户输入你提出一个问题。并行检索系统同时向“上下文向量库”和“记忆向量库”发起搜索寻找与问题语义最接近的文档片段和历史对话片段。动态组装Prompt系统将检索到的相关片段数量由/cc和/mc设定、当前的短期记忆如果开启以及预设的系统指令prompt.txt组合成最终的提示词。调用API将这个精心组装的、只包含最相关信息的提示词发送给OpenAI API如GPT-4。生成与存储获取AI回复并同时将本轮完整的问答对存入“长期记忆向量库”丰富其知识。为什么这样能省钱假设你有一个100页的PDF。传统方式是每次提问都把整个文档可能数万tokens塞进提示词。而Memory Bot可能只检索出其中3个最相关的段落几百个tokens。API收费是按输入和输出的总tokens数计算的这种方式能轻易将单次对话成本降低一个数量级。2.3 技术栈选型解析LangChain.js这是项目的基石。它抽象了与AI模型交互、记忆管理、文档加载、文本分割、向量化等复杂流程让开发者能专注于业务逻辑。Memory Bot 重度使用了它的ConversationChain、HNSWLib向量存储、以及各种DocumentLoader。HNSWLib一个高效的本地向量搜索库。选择它而非ChromaDB、Pinecone等方案是因为它无需额外部署数据库服务所有数据以文件形式保存在本地db目录简单、隐私性好、零延迟。缺点是索引文件较大且不适合分布式场景。OpenAI API提供核心的文本生成Chat Completion和向量化Embeddings能力。项目默认使用text-embedding-ada-002生成向量使用gpt-4或gpt-3.5-turbo生成回复。Node.js服务端运行环境利用其丰富的生态系统处理文件、网络请求等。这个选型组合在功能、易用性和隐私之间取得了很好的平衡特别适合个人或小团队在本地部署使用。3. 从零开始的详细部署与配置指南理论清楚了我们开始动手。以下步骤假设你已具备基本的命令行操作和Node.js环境知识。3.1 环境准备与项目初始化首先确保你的系统已安装Node.js建议版本16和npm。然后获取项目代码并安装依赖# 1. 克隆项目仓库 git clone https://github.com/gmickel/memorybot.git cd memorybot # 2. 安装依赖 npm install安装依赖的常见问题Windows用户注意项目依赖的hnswlib-node包需要本地编译。如果安装失败提示需要C构建工具你有两个选择安装Visual Studio Build Tools或Visual Studio勾选“使用C的桌面开发”工作负载。更推荐使用Windows Subsystem for Linux (WSL)在Linux子系统中运行项目能避开大多数Node.js原生模块的编译问题。网络问题如果npm install缓慢或失败可以尝试配置淘宝镜像npm config set registry https://registry.npmmirror.com3.2 关键配置.env 文件详解项目根目录下有一个.env.example文件复制它并重命名为.env。这个文件是你的核心配置文件每一行都至关重要。# 复制示例配置文件 cp .env.example .env用文本编辑器打开.env文件你需要配置以下参数# OpenAI API 密钥必填 OPENAI_API_KEYsk-your-actual-api-key-here # 使用的聊天模型默认为 gpt-4。如果没有GPT-4 API权限改为 gpt-3.5-turbo MODELgpt-4 # 向量嵌入模型一般无需修改 EMBEDDING_MODELtext-embedding-ada-002 # 上下文向量库的存储路径默认即可 CONTEXT_VECTOR_STORE_PATH./db/context # 记忆向量库的存储路径默认即可 MEMORY_VECTOR_STORE_PATH./db/memory # 初始加载的文档目录你的知识库放在这里 DOCS_DIR./docs # 聊天日志存储目录 CHAT_LOGS_DIR./chat_logs # 短期记忆窗口缓冲的大小即记住最近几轮对话 BUFFER_SIZE6安全警告.env文件包含你的API密钥务必将其添加到.gitignore中切勿提交到版本控制系统。OPENAI_API_KEY是你的付费凭证泄露会导致他人盗用产生费用。3.3 准备你的知识库初始上下文在启动机器人之前最好先给它“喂”一些资料。默认的文档目录是./docs里面有一个example.md文件。清空或替换你可以直接删除example.md或者用自己的文档覆盖它。支持格式将你的.txt,.md,.pdf,.docx,.epub,.csv文件放入docs文件夹。支持多种格式是LangChain的文档加载器带来的便利。文档处理逻辑启动时Memory Bot 会自动读取DOCS_DIR下的所有支持文件将它们分割成较小的文本块如500字符一段通过OpenAI的Embedding模型转换为向量然后存入CONTEXT_VECTOR_STORE_PATH指定的本地索引中。这个过程在首次启动或添加新文档时会需要一些时间。实操心得文档预处理质量大于数量确保文档内容清晰、结构良好。杂乱的格式或扫描质量差的PDF会影响文本提取效果。分割的重要性LangChain默认的分割策略可能不适合所有文档。如果发现检索不准可以后续研究修改src目录下的文本分割器TextSplitter配置比如调整块大小chunkSize和重叠区chunkOverlap。敏感信息再次提醒这些文档内容会被发送到OpenAI的API以生成向量。请勿上传任何敏感、机密或个人隐私信息。3.4 启动与首次对话完成配置和文档准备后就可以启动你的Memory Bot了。npm start如果一切顺利终端会显示初始化信息如“Loading documents from ./docs...”然后出现一个简洁的You:提示符。现在你可以像和朋友聊天一样输入问题了。首次对话示例You: 你好请介绍一下你自己。 Memory Bot: 我是一个由Memory Bot驱动的AI助手我拥有长期和短期记忆可以基于你提供的文档内容和你我的对话历史来回答问题。我目前的知识库中已经加载了一些文档作为上下文。有什么可以帮你的吗 You: 我的docs文件夹里放了一份关于Node.js的指南你能告诉我它里面讲了什么吗 Memory Bot: 系统会从向量库中检索与“Node.js指南”相关的文档片段并基于这些片段生成回答根据您提供的文档这份Node.js指南主要涵盖了从环境搭建、模块系统到HTTP服务器创建的基础知识...恭喜你的私人AI知识库助理已经上线了4. 核心功能实操与命令详解Memory Bot 的强大不仅在于启动更在于运行时的灵活控制。它提供了一系列命令以/开头来管理记忆、上下文和行为。4.1 动态管理上下文喂给它新的知识启动后你无需重启就能随时扩充它的知识库。/add-docs file1 file2 ...(或/docs)将docs目录下的新文件添加到上下文向量库。You: /add-docs 项目计划书.pdf 市场调研.md注意文件必须在DOCS_DIR默认./docs目录下。此命令会为这些文件生成向量并并入索引。/add-url url [selector] [maxLinks] [minCharLength](或/url)抓取网页内容。这是极其强大的功能。url: 起始网址。selector: (可选) CSS选择器用于定位要抓取的主要内容区域如article或.main-content。默认为body。maxLinks: (可选) 最大跟踪链接数用于抓取整个小型网站。默认为20需谨慎设置避免抓取过多。minCharLength: (可选) 忽略内容少于指定字符的页面。默认为200。You: /add-url https://example.com/blog/post-123 article You: /add-url https://docs.example.com “.docs-content” 5 500/add-youtube url或videoID(或/yt)添加YouTube视频转录稿。底层使用了youtube-transcript库。You: /add-youtube https://www.youtube.com/watch?vdQw4w9WgXcQ You: /add-youtube dQw4w9WgXcQ添加内容后的重要步骤添加完成后建议主动问一个关于新内容的问题以“激活”检索。系统有时不会立即在接下来的对话中用到新内容直到你提出相关查询。4.2 精细控制记忆与检索行为这是调优AI表现的核心直接关系到回答质量和API成本。/context-config 数字(或/cc)设置从上下文向量库你的文档库中检索多少条最相关的片段。默认是4。场景当你问一个复杂、需要综合多部分信息的问题时可以调高如/cc 8。当你的问题非常具体或想严格控制token用量时可以调低如/cc 2。设置为0则完全忽略文档上下文。You: /cc 6 Memory Bot: Context config updated. Will retrieve 6 relevant context documents./memory-config 数字(或/mc)设置从记忆向量库历史对话库中检索多少条最相关的历史对话片段。默认是4。场景在进行一个深度、连续的主题讨论时调高此值如/mc 6能让AI更好地联系之前的讨论。进行一次性、独立的新话题时可以调低或设为0。You: /mc 3/toggle-window-memory(或/wm)开关短期记忆窗口缓冲。关闭后AI将只基于向量检索到的长期记忆和上下文来回答完全忽略最近的对话顺序。这在某些需要纯粹基于文档问答的场景下有用。You: /wm Memory Bot: Window memory is now OFF.配置策略心得新手起步保持默认/cc 4和/mc 4是不错的选择在成本和效果间取得平衡。深度分析文档针对一本电子书或一份长报告进行问答可以将/cc提高到 8-10/mc降低到 1-2。创造性对话如果是脑暴或开放式聊天可以降低/cc甚至为0提高/mc如6让对话更连贯、更有“人情味”。总Token估算每次检索的片段数直接乘以每个片段的平均token数约100-300再加上你的问题和系统指令就能大致估算输入token量。灵活调整这两个参数是控制成本的关键手段。4.3 项目管理与多任务切换Memory Bot 支持多项目隔离这是其设计的一大亮点。/list-context-stores(或/lcs)列出所有已创建的上下文存储库。每个库对应一个知识领域或项目。/change-context-store 子目录名(或/ccs)切换或创建一个新的上下文向量库。You: /lcs Memory Bot: Available context stores: [‘default‘ ‘project_alpha‘ ‘research_papers‘] You: /ccs research_papers Memory Bot: Switched to context store: research_papers. (This store is empty.)执行/ccs new_project后系统会在./db下创建new_project文件夹用于存储新的上下文向量。你之后用/add-*命令添加的文档都会进入这个新库。记忆库是共享的请注意记忆向量库对话历史目前是全局共享的不随上下文库切换而改变。这意味着你的对话历史会跨越不同项目。使用场景你可以为“工作项目A”、“个人学习B”、“小说创作C”分别创建不同的上下文库。通过/ccs快速切换确保和AI讨论工作时它不会用你小说的内容来回答技术问题保持了知识的纯净性。4.4 其他实用命令/reset重置当前对话。这会清空短期记忆窗口缓冲和长期记忆向量库。但不会删除已加载的文档上下文向量库。如果你想开始一个全新话题且不希望AI参考任何过往聊天记录就用这个命令。/help(或/h,/?)显示所有命令的帮助信息。/quit(或/q)退出程序。5. 高级技巧、问题排查与优化掌握了基本操作后一些高级技巧和问题排查方法能让你用得更顺手。5.1 优化提示词System Prompt系统的“性格”和回答方式很大程度上由src/prompt.txt文件决定。默认的提示词可能比较通用你可以修改它来定制AI的行为。例如你可以让它更简洁你是一个专业、精准的助手。请严格基于提供的上下文和对话历史来回答问题。如果信息不足请直接说明“根据现有资料无法回答”。回答请尽量简洁使用要点列表。或者赋予它一个角色你是一位资深软件开发架构师。请用严谨的技术语言回答问题在涉及方案选择时请分析利弊。你的回答应体现专业深度。修改提示词后需要重启Bot (CtrlC后再次npm start) 才能生效。5.2 理解与处理“幻觉”问题即使有了向量检索AI仍然可能产生“幻觉”即编造信息。这通常源于检索失败你的问题与文档中的任何片段语义相似度都不高导致检索不到相关内容AI只能凭自身知识生成可能不准确的答案。检索不全相关答案分散在多个片段中但/cc设置过低未能检索全。模型本身倾向大语言模型有内在的“创造”倾向。应对策略优化提问尝试使用文档中可能存在的关键词进行提问。调整检索参数适当提高/cc值。指令约束在prompt.txt中加强指令如“务必引用上下文中的原话”、“如果未在上下文中找到明确依据请回答‘我不知道’”。交叉验证对于关键信息可以要求AI指出其回答依据的原文片段虽然Memory Bot当前未直接提供此功能但你可以通过追问“你这个结论出自文档的哪一部分”来验证。5.3 常见问题与解决方案速查表问题现象可能原因解决方案启动时报错提示MODEL相关没有GPT-4 API权限但.env中MODELgpt-4将.env中的MODEL改为gpt-3.5-turbonpm install失败提示hnswlib-node编译错误Windows环境缺少C编译工具安装Visual Studio Build Tools或使用WSL运行项目添加PDF文档后AI回答完全无关PDF是扫描件或排版复杂文本提取失败使用OCR软件先将PDF转换为可检索的文本PDF或直接提供文本文件使用/add-url后进程卡住或报错网站有反爬机制或网络不稳定尝试添加--user-agent等头信息需修改代码或手动复制网页内容保存为.txt文件再用/add-docsAI的回答似乎没有用到我刚刚添加的文档新文档的向量尚未被检索到或提问方式不匹配1. 用文档中的特定术语或句子片段提问。2. 稍等片刻再试索引加载需要时间。3. 检查文档是否成功加载查看启动日志或db/context目录文件大小是否有变化。对话历史似乎没有被正确引用/mc设置过低或历史对话的向量化未能捕捉到相关性1. 适当提高/mc值。2. 在提问时更明确地关联历史对话例如“接着我们刚才关于XX的讨论...”。程序运行一段时间后响应变慢向量索引文件变大检索耗时增加HNSWLib是本地索引性能随数据量增长会下降。可定期清理不用的上下文库删除db/context下对应子目录或考虑将历史记忆库重置 (/reset)。5.4 性能与成本监控建议成本监控定期查看OpenAI平台的使用仪表盘。关注Usage页面特别是Embedding和Chat Completion的token消耗。每次使用/add-*命令都会产生Embedding费用每次对话则产生Completion费用。日志查看所有对话都保存在./chat_logs目录下按日期命名。这不仅用于回顾也可以在出现奇怪回答时查看当时AI实际接收到的完整Prompt是什么是调试的宝贵资料。索引管理./db目录会随着使用不断增大。如果某个上下文库不再需要可以直接在文件系统中删除对应的文件夹如rm -rf ./db/context/old_project。记忆库./db/memory如果过大可以通过/reset命令清空重建。Memory Bot 将一个强大的“外部大脑”概念产品化通过清晰的架构和实用的命令让普通人也能轻松驾驭基于大模型和私有知识的深度对话。它可能不是功能最全的图形界面应用但其命令行交互的简洁性和架构的透明性对于开发者和技术爱好者来说恰恰是学习和定制的最佳起点。你可以基于它的代码轻松地将其改造成一个HTTP API服务集成到你自己的应用中去。