agentmemory：给AI Coding Agent装上持久记忆，让每次会话都"认识"你的项目

"用Cursor写了两周代码，第三周打开新会话，全忘了。"这是每个AI Coding Agent用户的痛。agentmemory（⭐4,408）专门解决这个——持久化记忆，让AI真正理解你的项目上下文。

引言：AI Coding Agent的"失忆症"

用过Claude Code、Cursor、Cline的朋友，有没有这种感觉：

• 第一天：AI很懂你的项目
• 第五天：需要重新解释项目背景
• 第十天：每次开新会话都是从零开始

这不是AI不够聪明，是它压根没有记忆能力——每次会话结束，上下文全丢了。

agentmemory就是来解决这个问题的：给AI Coding Agent装上持久化记忆，让它"记住"项目的历史、决策、偏好。

什么是agentmemory？

agentmemory是一个专门为AI Coding Agent设计的持久化记忆系统，基于真实世界基准测试打造（不是拍脑袋造的）。

核心特点：

• TypeScript原生：和Cursor/Cline/Copilot同语言，无缝集成
• 真实基准测试驱动：不是YY需求，是从实际使用中提炼的功能
• 多Agent支持：Claude Code、Cursor、Cline、Copilot都能用
• 持久化存储：会话结束不丢数据，下次打开还有
• 增量更新：自动从对话中学习新知识，不需要你手动维护

核心功能深度解析

1. 多级记忆架构

agentmemory不是简单的key-value存储，它有层级设计：

project_context/     # 项目级：项目是什么、技术栈、架构设计
  ├── overview/     # 总体概述
  ├── architecture/  # 架构决策
  └── decisions/    # 重要决定记录

codebase_memory/    # 代码级：具体代码的意图、坑点
  ├── patterns/     # 代码模式记录
  ├── conventions/  # 代码规范
  └── hotspots/     # 容易出问题的区域

session_history/    # 会话历史
  ├── completed/    # 已完成的任务
  └── failed/       # 失败的尝试（同样重要）

preferences/        # 用户偏好
  ├── coding_style/ # 编码风格偏好
  └── tool_prefs/  # 工具选择偏好

2. 智能检索

不是简单的关键词匹配，是语义理解级别的检索：

import { AgentMemory } from 'agentmemory';

const memory = new AgentMemory();

// 检索"上次在哪里遇到了什么问题"
const result = await memory.recall(
  "为什么之前没用这个API",
  { 
    scope: 'codebase_memory', 
    topK: 5,
    threshold: 0.7  // 语义相似度阈值
  }
);

// result: [
//   "第3会话：因为那个API在v2版本deprecated了，改用xxx替代",
//   "第7会话：这里有循环引用问题，已用xxx方案绕过",
//   ...
// ]

3. 自动上下文注入

最实用的功能——新会话开始时自动注入相关记忆：

// 在Agent的system prompt中调用
async function getContextPrompt(agent: AICodingAgent) {
  const context = await memory.getRelevantContext(
    agent.currentSession.projectPath,
    { 
      maxTokens: 4000,  // 控制上下文长度
      prioritize: ['recent', 'relevant', 'unresolved']
    }
  );
  
  return `项目上下文：
${context}

以上是你之前的工作记录，请继续。`;
}

4. 多Agent同步

团队多人用同一个Agent？没问题：

// 共享项目记忆
const sharedMemory = new AgentMemory({
  storage: 'shared',  // 团队共享存储
  sync: true          // 实时同步
});

// 个人偏好隔离
const personalMemory = new AgentMemory({
  storage: 'personal'
});

与同类工具对比

对比项	agentmemory	MemGPT	Mem0	Zep
专注领域	Coding Agent专用	通用LLM	通用LLM	AI对话
语言	TypeScript原生	Python	多语言	Python
Agent集成	Cursor/Cline/Copilot	❌	⚠️ 有限	⚠️ 有限
基准测试	✅ 真实场景驱动	❌	❌	❌
持久化	✅ 文件/DB	✅	✅	✅
增量学习	✅ 自动	✅	✅	✅
团队共享	✅ 支持	❌	⚠️ 企业版	⚠️ 企业版
安装复杂度	⭐ 低（npm包）	⭐ 中	⭐ 中	⭐ 中
适用场景	Coding Agent用户	通用AI助手	通用AI助手	客服机器人

实战安装与使用

安装

# npm
npm install agentmemory

# 或 yarn
yarn add agentmemory

# 或 pnpm
pnpm add agentmemory

基本使用（5分钟上手）

import { AgentMemory } from 'agentmemory';

// 1. 初始化
const memory = new AgentMemory({
  projectPath: '/path/to/your/project',
  storage: './.agentmemory'  // 本地存储位置
});

// 2. 开启新会话时恢复上下文
await memory.initSession();
const context = await memory.getContext();
console.log(context);
// 输出: "项目：电商后端API\n技术栈：FastAPI + PostgreSQL\n上次任务：实现了用户认证模块..."

// 3. 完成任务后保存记录
await memory.remember({
  type: 'task_completed',
  content: '完成了订单模块的开发，包括创建/查询/取消订单API',
  tags: ['order', 'api', 'fastapi'],
  sessionId: memory.currentSession.id
});

// 4. 遇到问题时记录"坑"
await memory.remember({
  type: 'gotcha',
  content: '这个地方的循环引用问题用EventEmitter模式绕过了，不要改成直接调用',
  tags: ['circular-reference', 'gotcha'],
  importance: 'high'  // 高重要性，会被优先检索
});

// 5. 关闭会话时总结
await memory.closeSession({
  summary: '完成了订单模块，修复了3个bug，遗留1个：支付回调的幂等性处理'
});

与Claude Code集成

// 在.claudeirc 或初始化脚本中
import { AgentMemory } from 'agentmemory';

const memory = new AgentMemory({
  projectPath: process.cwd()
});

// Claude Code的system prompt钩子
memory.injectIntoPrompt({
  maxLength: 3000,
  includeTypes: ['overview', 'gotcha', 'recent_tasks']
});

与Cursor集成

// Cursor的.mcp.json或扩展配置
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["agentmemory", "server"]
    }
  }
}

避坑指南

⚠️ 坑点1：存储空间无限增长

问题：记忆文件越来越大的，最后几MB的上下文根本装不下。

解决：定期压缩和清理

// 定期执行
await memory.compact({
  maxSize: '10MB',
  keepRecent: 50,  // 保留最近50条
  keepHighImportance: true
});

// 或者设置自动压缩
const memory = new AgentMemory({
  autoCompact: true,
  maxSize: '10MB'
});

⚠️ 坑点2：敏感信息泄露

问题：代码库里的密码、API密钥被记到记忆里了。

解决：敏感信息过滤

const memory = new AgentMemory({
  sensitivePatterns: [
    /api[_-]?key/i,
    /password/i,
    /secret/i,
    /token/i
  ],
  redactSensitive: true
});

// 或者手动标记
await memory.remember({
  content: '数据库连接字符串是：xxx',  // 不会被存储
  isSensitive: true
});

⚠️ 坑点3：跨项目记忆混淆

问题：多个项目用同一个记忆，导致上下文混乱。

解决：严格的项目隔离

// 每个项目用独立的storage
const memory = new AgentMemory({
  storage: `./.agentmemory/${projectName}`,
  projectId: projectName  // 显式指定
});

⚠️ 坑点4：与Copilot的context重叠

问题：agentmemory和Copilot的context机制冲突，token爆炸。

解决：控制上下文长度

await memory.getContext({
  maxTokens: 2000,  // 不要贪多
  prioritizeBy: 'recency'  // 优先最新
});

适用场景

• ✅ 长期项目维护：需要AI记住几个月的项目上下文
• ✅ 多Agent协作：团队多个开发者用同一个项目
• ✅ 复杂重构：AI需要理解历史决策才能安全重构
• ✅ 知识传承：项目交接时，AI可以"继承"前任的工作记录
• ✅ Cursor/Cline重度用户：这类工具本身没有记忆，更需要

不适用场景

• ❌ 一次性脚本：写完就丢，不需要记忆
• ❌ 简单项目：几行代码，从零开始也不费劲
• ❌ 对数据隐私极度敏感：本地存储虽有，仍是文件形式
• ❌ 不想安装npm包：需要一定的工程化能力

总结

agentmemory解决的是一个真实存在的痛点——AI Coding Agent的失忆症。它不是通用记忆库，而是专门为Coding场景设计的，从多级记忆架构到智能检索，从自动上下文注入到多Agent同步，每个功能都直击痛点。

如果你每天都在用Cursor/Claude Code/Cline开发，重度用户强烈建议试试。它不能让你少写代码，但能让AI每次都"认识"你的项目，省去大量重复解释的时间。

项目地址：https://github.com/rohitg00/agentmemory Star：4,408 | License：MIT | 语言：TypeScript