1. 项目概述：为AI编程助手装上本地持久记忆

如果你和我一样，每天都在和Cursor、Claude Code这类AI编程助手打交道，那你一定遇到过这个让人头疼的场景：每次开启一个新的会话，你都得像个复读机一样，把项目背景、技术栈、昨天刚改完的bug、甚至和同事争论后定下的某个架构决策，再从头到尾解释一遍。AI助手就像一个只有七秒记忆的金鱼，每个会话都从零开始，这不仅浪费了宝贵的上下文窗口，更消磨了我们的耐心。我们需要的不是一个每次都从零开始的“临时工”，而是一个能记住项目历史、理解上下文、真正成为我们得力伙伴的“老员工”。

这就是Awareness Local要解决的核心痛点。它本质上是一个 本地优先的AI助手记忆系统 。你可以把它想象成给你的AI编程助手外接了一个本地大脑。这个“大脑”以守护进程的形式运行在你的电脑上，将所有对话、决策、代码变更和项目知识，以人类可读的Markdown文件形式存储下来。下次当你再问助手“我们之前为什么选择PostgreSQL而不是MySQL？”时，它不再是一脸茫然，而是能立刻从记忆中调取相关的决策记录，告诉你当时的权衡利弊。

最吸引人的是它的“无感”集成。它通过 MCP协议 与你的IDE通信，这意味着你几乎不需要改变现有的工作流。无论是Cursor、Claude Code、Windsurf，还是其他十几种支持MCP的IDE，只需一行命令 npx @awareness-sdk/setup ，记忆系统就部署好了。你的数据完全留在本地，无需注册任何云账户，真正实现了隐私、安全和离线可用。对于注重代码隐私的开发者、在受限网络环境下工作的团队，或者只是单纯不想把项目细节上传到第三方服务器的个人来说，这是一个极具吸引力的方案。

2. 核心架构与工作原理拆解

Awareness Local的设计哲学非常清晰： 简单、透明、高效 。它没有选择构建一个复杂晦涩的黑盒系统，而是采用了一套组合巧妙、各司其职的技术栈，共同构建起一个可靠的记忆层。

2.1 数据存储：Markdown与SQLite的黄金组合

所有记忆的最终归宿是本地文件系统中的一个 .awareness/ 目录。这个设计深得我心，因为它遵循了“人类可读优先”的原则。

.awareness/
├── memories/
│   ├── 2024-03-22_decided-to-use-postgresql-for-json-support.md
│   ├── 2024-03-23_fixed-auth-token-expiry-bug-in-user-service.md
│   └── ...
├── knowledge/
│   ├── decisions/postgresql-over-mysql.md
│   ├── solutions/implement-refresh-token-rotation.md
│   └── risks/circular-dependency-in-module-a.md
├── tasks/
│   ├── open/implement-api-rate-limiting.md
│   └── closed/migrate-legacy-logging-system.md
└── index.db

• memories/ ：这里按日期存储原始的会话记忆。每个文件都是一个Markdown文档，记录了某次对话中捕获的关键信息。因为是纯文本，你可以直接用任何编辑器打开、查看甚至修改。更重要的是， 它可以被纳入版本控制系统 。想象一下，把 .awareness/memories/ 目录也提交到Git，团队新成员克隆项目后，AI助手就能立刻“继承”这个项目的全部历史记忆， onboarding 过程瞬间加速。
• knowledge/ ：这是系统自动从原始记忆中提炼出的结构化知识。Awareness Local内置了知识提取功能，它会分析记忆内容，自动识别出“决策”、“解决方案”、“风险”等类别，并生成对应的知识卡片。例如，当你在多次对话中反复讨论并最终决定使用PostgreSQL的JSONB字段时，系统可能会生成 knowledge/decisions/postgresql-over-mysql.md 这张卡片，清晰罗列选择理由、权衡点和参考资料。
• tasks/ ：用于跟踪项目中提及的待办事项。AI助手在对话中捕捉到“我们接下来需要实现限流”这样的信息时，可以自动或经你确认后，在此创建一个任务条目。
• index.db ：这是一个SQLite数据库文件，它是实现快速检索的核心。原始Markdown文件便于人类阅读和版本管理，但不适合高频检索。因此，系统会异步地将文件内容索引到这里的FTS5（全文搜索）表中，并为可选的字向量创建索引。

这种“原始文件+索引数据库”的架构，在透明性和性能之间取得了绝佳的平衡。数据主权完全在你手中。

2.2 混合检索引擎：FTS5与向量搜索的协同

记忆存得好，更要找得快、找得准。Awareness Local的检索能力是其技术亮点，它采用了 混合检索 策略，结合了关键词搜索和语义搜索的优势。

1. SQLite FTS5（关键词搜索） ：这是第一道快速过滤网。FTS5是SQLite内置的全文搜索引擎，对于代码片段、函数名、错误信息、特定技术名词（如“PostgreSQL”、“JWT”）这类精确匹配的查询，它的速度极快，结果准确。例如，你问“之前是怎么处理JWT过期的？”，FTS5能瞬间从所有记忆中定位包含“JWT”和“过期”关键词的文档。

2. 本地向量嵌入（语义搜索） ：关键词搜索的局限在于它无法理解同义词和语义关联。比如，你问“用户认证那块我们是怎么设计的？”，而记忆文件中可能写的是“实现了基于令牌的身份验证”。这时就需要语义搜索。Awareness Local默认使用 all-MiniLM-L6-v2 这个轻量级模型（仅需约80MB），将文本转换为384维的向量。当进行搜索时，查询语句也会被转换成向量，系统通过计算余弦相似度来找到语义上最相关的记忆。你可以通过 npm i @huggingface/transformers 来启用这个功能。

3. 混合RRF排名 ：系统并非二选一，而是将两者的结果通过 Reciprocal Rank Fusion 算法进行融合。简单来说，一个记忆在关键词搜索结果中排名越高，同时在语义搜索结果中排名也越高，那么它在最终混合结果中的排名就会更高。根据项目提供的消融实验数据，纯向量搜索的R@5为92.6%，纯BM25（一种经典的关键词评分算法）为91.4%，而混合RRF方法达到了95.6%，显著优于任一单一方法。这3%的提升在实际体验中意味着更少的相关记忆遗漏，AI助手给出的上下文更精准。

实操心得：向量模型的选择 使用 all-MiniLM-L6-v2 是一个在精度和资源消耗间非常平衡的选择。它在消费级硬件（如Apple M1）上运行流畅，无需GPU。如果你的项目涉及非常专业的领域术语（如特定生物医学词汇），可以考虑微调嵌入模型或切换为领域专用模型，但这会引入额外的复杂性和资源开销。对于绝大多数软件开发场景，默认模型已完全足够。

2.3 MCP协议：无缝连接IDE的桥梁

MCP 是这一切能无缝工作的关键。你可以把它理解为AI助手领域的“语言”。它定义了一套标准协议，让不同的AI助手（客户端）能够发现和调用本地或远程的工具（服务器）。Awareness Local 就是一个实现了MCP协议的服务器。

安装后，Awareness Local 守护进程会在 localhost:37800 启动一个MCP服务器。你的IDE（如Cursor）在启动时，会通过配置发现这个本地服务器，并与之建立连接。之后，IDE内置的AI助手就能直接调用Awareness Local提供的“工具”了。整个过程对开发者完全透明，你不需要在IDE里写任何胶水代码。

3. 完整安装与配置实战

理论很美好，现在我们来动手把它装起来，并集成到你最常用的IDE中。整个过程力求一步到位。

3.1 基础环境准备与一键安装

首先确保你的系统满足最低要求： Node.js 18或更高版本 。你可以通过 node --version 来检查。

安装过程简单到不可思议：

npx @awareness-sdk/setup

运行这条命令，它会自动完成以下工作：

1. 在全局或当前项目下安装 @awareness-sdk/cli 等相关包。
2. 启动一个本地的Awareness守护进程。
3. 尝试自动检测你系统中已安装的、支持MCP的IDE（如Cursor, Claude Code等）。
4. 引导你完成IDE的配置，通常是自动或半自动地向IDE的MCP配置文件（如 cursor/mcp.json 或 claude-desktop/config.json ）中添加指向本地守护进程的配置项。

安装完成后，你应该能在终端看到守护进程成功启动的消息，并提示Web控制台的访问地址（通常是 http://localhost:37800 ）。

3.2 主流IDE配置详解

虽然 npx setup 命令试图自动配置，但了解手动配置的备份方案至关重要，因为自动检测可能因IDE版本或安装路径而失败。

对于Cursor： Cursor的MCP配置通常位于 ~/.cursor/mcp.json 。安装程序会尝试写入类似以下配置：

{
  "mcpServers": {
    "awareness-local": {
      "command": "npx",
      "args": [
        "-y",
        "@awareness-sdk/cli",
        "serve"
      ],
      "env": {
        "AWARENESS_DATA_DIR": "/path/to/your/project/.awareness"
      }
    }
  }
}

如果自动配置失败，你可以手动创建或编辑此文件。 AWARENESS_DATA_DIR 环境变量用于指定记忆存储的根目录。如果不设置，默认会使用一个全局目录。 我强烈建议将其设置为项目路径 ，这样每个项目都有独立的记忆库。

对于Claude Code： Claude Code的配置方式可能更偏向于通过其插件市场或图形界面。根据文档，你可以通过指令 /plugin marketplace add edwin-hao-ai/Awareness-SDK 来添加源，然后安装 awareness-memory 插件。插件会处理背后的MCP连接。

对于Windsurf、Zed等： 这些编辑器通常也遵循类似的MCP配置模式。你需要找到其对应的MCP配置文件路径（通常在用户配置目录下），并添加相应的服务器配置。关键在于 command 和 args 要指向正确的CLI路径。

重要注意事项：端口冲突 Awareness Local 默认使用 37800 端口。如果该端口已被占用，守护进程可能启动失败。你可以通过环境变量 AWARENESS_PORT 来指定另一个端口，例如 AWARENESS_PORT=37801 npx @awareness-sdk/cli serve ，同时在IDE的MCP配置中更新对应的连接端口。

3.3 验证安装与Web控制台

安装配置完成后，通过以下方式验证：

1. 检查进程 ：运行 ps aux | grep awareness 或查看系统任务管理器，确认 awareness 相关进程在运行。
2. 访问控制台 ：在浏览器中打开 http://localhost:37800 。你应该能看到Awareness Local的Web控制台。这里是一个可视化界面，可以浏览所有记忆、知识卡片和任务，也是管理云同步（如果需要）的入口。
3. 在IDE中测试 ：在你的IDE中，新建一个会话，尝试向AI助手提问一个关于当前项目的问题。如果配置成功，助手应该能调用记忆工具。在Claude Code或Cursor中，你有时能在AI的回复中看到它调用了 awareness_recall 这样的工具。

4. 核心工作流与MCP工具实战

系统运行起来后，你和AI助手的交互方式会发生微妙而强大的变化。这一切是通过几个核心的MCP工具实现的。了解它们，你就能更好地理解和引导助手的行为。

4.1 会话初始化： awareness_init

当你在一个项目目录下开启一个新的AI会话时，助手首先应该做的是调用 awareness_init 。这个工具的作用是 加载会话上下文 。它会返回：

• 近期知识 ：最近记录的一些关键决策或解决方案。
• 进行中的任务 ：从 tasks/open/ 目录中列出的待办事项。
• 项目规则/规范 ：可能从特定知识卡片中提取的编码规范、部署流程等。

这相当于在对话开始前，先给AI助手递上了一份“项目简报”，让它快速进入状态，避免问出一些非常基础或已有定论的问题。

4.2 记忆记录： awareness_record

这是构建记忆库的核心。在对话过程中，当发生了值得记录的事情时，就应该调用此工具。这可以是手动触发，也可以通过一些IDE插件自动捕获（如在执行完一段代码生成后）。记录的内容包括：

• 内容 ：发生了什么？例如，“将用户服务的数据库连接池从HikariCP切换到了Vibur，因为观察到在峰值负载下连接泄漏。”
• 类型 ：这是一个“决策”、“代码变更”、“问题”、“洞察”还是“会议记录”？
• 关联资源 ：可以关联到具体的文件、Git提交哈希、问题追踪ID等。

关键在于， awareness_record 不仅仅是存档。它内部会进行知识提取 。系统会分析你记录的这段文本，尝试自动识别并创建或更新 knowledge/ 目录下的结构化知识卡片。例如，上面的记录可能会同时更新 knowledge/decisions/connection-pool-selection.md 和 knowledge/solutions/connection-leak-under-load.md 。

4.3 记忆检索： awareness_recall 与渐进式披露

这是最常用的工具，也是其智能所在。它实现了 “渐进式披露” 策略，以优化大模型宝贵的上下文窗口。

传统暴力方法 ：一次性把所有相关记忆的全文塞进提示词，很快会耗尽上下文限额，且大部分内容可能不相关。

Awareness的渐进式披露 ：

1. 第一阶段 - 获取摘要列表 ：AI助手首先调用 awareness_recall(query, detail="summary") 。系统返回一个包含记忆标题、简短摘要（约80个tokens）和相关性分数的列表。
   • 输出示例 ：

     [
       {id: 1, title: “选择PostgreSQL而非MySQL的决策”, summary: “因需原生JSON支持及更佳的GIS功能，于2024-03-22决定。”, score: 0.95},
       {id: 2, title: “修复用户认证令牌过期问题”, summary: “2024-03-23，通过实现双令牌（access+refresh）机制解决。”, score: 0.87},
       ...
     ]
     

2. 第二阶段 - 按需获取详情 ：AI助手（或用户）浏览这个摘要列表，挑选出真正需要深入查看的几条记忆（比如ID为1和2的）。然后，它再调用 awareness_recall(detail="full", ids=[1, 2]) ，获取这两条记忆的完整、未经删减的内容。

这种方法 极大地提升了token使用效率 ，确保送入大模型的都是高相关性的精华信息，让AI助手的回答更精准、更有依据。

4.4 快速查找与多智能体支持

• awareness_lookup ：用于快速查询特定类型的信息，如“给我所有未完成的任务”或“列出所有标记为‘风险’的知识卡片”。它比 awareness_recall 更轻量，目标更明确。
• awareness_get_agent_prompt ：在更复杂的多智能体工作流中，不同的AI角色（如“架构师”、“代码审查员”、“测试员”）可能需要不同的上下文提示。这个工具可以为特定角色生成定制的提示词片段，集成其相关的记忆和知识。

5. 高级特性与生态集成

当你熟悉了基础工作流后，可以探索这些进阶功能，它们能进一步提升体验。

5.1 可选的云同步

Awareness Local是本地优先的，但它也提供了可选的云同步功能（需要访问 awareness.market ）。云同步带来几个好处：

• 跨设备同步 ：在家里的台式机和公司的笔记本上无缝切换，记忆始终最新。
• 增强的语义搜索 ：云端可能使用更大、更强大的多语言向量模型，提升搜索质量。
• 团队协作 ：团队成员可以共享一个项目的记忆库，加速知识流转。
• 记忆市场 ：可以探索和集成一些公开的、非敏感的项目知识模板。

启用云同步非常简单，在Web控制台 ( localhost:37800 ) 点击“Connect to Cloud”，或用命令行 npx @awareness-sdk/setup --cloud 。你的本地数据会通过端到端加密的方式同步，你仍然拥有数据的完全控制权。

5.2 SDK与插件生态

Awareness不仅仅是一个本地工具，它正在形成一个围绕“AI记忆”的生态。

• Python/TypeScript SDK ( awareness-memory-cloud / @awareness-sdk/memory-cloud )：这两个SDK提供了 wrap_openai() 和 wrap_anthropic() 这样的包装器函数。这意味着你可以在自己的Python或Node.js脚本中，直接给OpenAI或Anthropic的API客户端套上这个“记忆层”。任何通过这个被包装的客户端发出的请求，都会自动先查询记忆、再注入上下文，让你的自定义AI应用也具备持久记忆能力。
• OpenClaw 插件 ：对于OpenClaw用户，有专门的插件可以实现 自动回忆 和 自动捕获 。插件会监控对话，在适当时机自动触发 awareness_recall 来获取背景，并在对话结束时自动建议记录关键点，进一步减少手动操作。
• Claude Code 技能包 ：提供了更深度集成的技能和钩子，优化在Claude Code中的交互体验。

6. 性能实测、问题排查与优化建议

任何工具，光说不练假把式。下面结合我的实际使用经验，谈谈性能表现和可能遇到的问题。

6.1 性能与资源消耗实测

在我的开发机（Apple M2, 16GB RAM）上，针对一个中等规模（约500条记忆）的项目：

• 守护进程内存占用 ：常驻内存约120MB。这对于现代开发机来说几乎无感。
• 检索速度 ： awareness_recall 的摘要查询通常在 100-300毫秒 内返回结果，即使启用本地向量搜索。全文检索根据返回内容大小，通常在1秒内。这个延迟在AI助手思考的间隙中完成，用户体验是流畅的。
• 索引重建 ：如果你手动修改了 .awareness/memories/ 下的Markdown文件，系统会检测到变化并在后台异步重建索引。对于几十条记录的增量更新，几乎是瞬间完成。首次初始化或大量文件变更时，可能需要几秒到十几秒。

6.2 常见问题与排查指南

即使设计得再完善，在实际部署中也可能遇到一些小麻烦。下面是一个快速排查表：

问题现象	可能原因	解决方案
IDE中AI助手完全不提记忆	1. MCP配置未生效或错误。 2. Awareness守护进程未运行。	1. 检查IDE的MCP配置文件路径和内容是否正确。重启IDE。 2. 在终端运行 npx @awareness-sdk/cli serve 手动启动，观察有无报错。检查端口 37800 是否被占用。
Web控制台 ( localhost:37800 ) 无法访问	守护进程未启动或启动在其它端口。	在终端用 lsof -i :37800 查看端口占用。尝试用 AWARENESS_PORT=37801 指定新端口重启。
检索结果不相关或为空	1. 记忆库尚未积累内容。 2. 查询语句过于模糊或与记忆内容表述差异大。 3. 向量模型未安装（仅影响语义搜索）。	1. 主动使用 awareness_record 记录一些关键信息。 2. 尝试更具体的关键词查询。在Web控制台测试不同查询词。 3. 运行 npm i @huggingface/transformers 安装向量模型依赖。
自动知识提取不准确	系统提取的“决策”、“风险”等分类有误。	这是当前AI的普遍局限。最佳实践是： 在记录记忆 ( awareness_record ) 时，手动为其指定一个清晰的类型和标题 。高质量的输入是高质量记忆库的基础。
同步冲突（启用云同步后）	多设备同时修改了同一条记忆。	系统通常会保留时间戳最新的版本，并在控制台给出冲突提示。建议团队内约定，对于关键决策记录，以某个主记录为准。

6.3 使用技巧与最佳实践

1. 主动记录，而非依赖自动 ：虽然未来插件会更智能，但目前阶段，养成在完成一个重要讨论、解决一个复杂bug或做出一个架构决定后， 主动触发记录 的习惯。花10秒钟记录，可能节省未来10分钟的解释时间。
2. 为记忆撰写好标题 ： awareness_record 时的标题是检索的第一线索。使用包含关键名词和动词的陈述句，如“ 决定 使用Redis Streams处理异步任务队列而非RabbitMQ， 原因 是更简单的分区模型”。
3. 项目级隔离 ：通过 AWARENESS_DATA_DIR 环境变量，为每个项目设置独立的 .awareness 目录。避免不同项目的记忆互相干扰，也便于通过Git管理。
4. 定期回顾与清理 ：偶尔通过Web控制台浏览你的记忆库。合并重复的记忆，为旧记忆添加标签（可通过编辑Markdown文件），归档已不再相关的信息。一个干净、高质量的记忆库比一个庞大、杂乱的无序集合有用得多。
5. 善用知识卡片 ：鼓励团队将达成的共识、制定的规范，以结构化的方式直接创建或更新到 knowledge/ 目录下。这可以作为项目的“活文档”，直接被AI助手引用。

经过一段时间的深度使用，我的体会是，Awareness Local带来的最大改变不是某个具体功能的提升，而是一种 工作范式的转变 。它让AI助手从“会话工具”变成了“项目伙伴”。那种无需重复解释背景、助手能基于历史上下文给出连贯建议的体验，一旦习惯就再也回不去了。它尤其适合长期、复杂的项目开发，以及需要多人协作的场景。虽然初期需要一点培养记录习惯的成本，但长期来看，它为项目积累的结构化知识资产，其价值远超投入。