project-sess-summary

name	project-sess-summary
description	Use when managing project session memory — summarizing conversations into dimension-specific markdown files, storing them in a memory/ directory, vectorizing with jcemb, and recalling context in new sessions to avoid重复沟通 and lost context.
version	1.0.0
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["memory-management","session-context","vector-retrieval","jcemb","project-memory"],"related_skills":["writing-plans","llm-wiki"]}}

项目会话记忆管理 (Project Session Memory Management)

一、核心技能总览

本技能文档围绕「项目会话记忆管理」展开，适配「对话总结→文件落盘→向量检索→上下文延续」全流程，核心目标是解决AI开发Agent对话失忆、重复沟通、重复检索的痛点，无需复杂代码RAG，聚焦轻量记忆管理与jcemb向量工具联动，降低开发成本，提升迭代效率。

核心技能：对话维度总结、记忆文件规范管理、自制向量jcemb工具使用、新对话上下文召回。

二、核心技能详解（实操性优先）

技能1：对话维度总结（核心必备）

1.1 维度选择原则

• 每次对话结束，仅选择「单一维度」总结，避免多维度混杂导致检索噪声

• 维度匹配场景：

• 新需求对接、业务规则确认 → 选择「需求与业务约束」维度

• 架构设计、模块划分、技术选型 → 选择「架构与模块设计」维度

• 编码规范、写法约定、避坑规则 → 选择「编码规范与写法约定」维度

• 功能修改、问题排查、复盘 → 选择「修改记录与踩坑总结」维度

• 接口、函数设计、参数约定 → 选择「接口与函数设计约定」维度

特殊场景：对话包含多维度内容，拆分多个文件分别总结（一个维度一个文件）

1.2 Prompt使用规范

• 所有总结均使用配套Prompt模板，不随意修改模板结构（确保向量检索时语义统一）

• 替换{{chat_history}}时，仅粘贴「有效开发对话」，剔除闲聊、试错、重复无效内容

• 输出要求：严格遵循Markdown结构化格式，不扩写、不啰嗦，仅记录事实、约定、约束

• 检查要点：生成后核对是否包含该维度核心信息，避免遗漏关键约束、约定或踩坑点

技能2：记忆文件管理（规范落地）

2.1 目录规范

• 固定目录：每个项目根目录下新建「memory/」文件夹，所有记忆文件统一存放

• 目录权限：确保可读写，方便后续自制向量jcemb工具扫描、读取文件

• 归档规则：项目迭代结束后，可在memory目录下按版本/模块新建子目录归档（如memory/v1.0/、memory/user模块/）

2.2 文件命名规范（强制）

• 命名格式：YYYY-MM-DD_维度名称_简短主题.md（无空格、无特殊字符）

• 维度名称统一写法（与Prompt维度一致）：

• 需求与业务约束

• 架构与模块设计

• 编码规范与写法约定

• 修改记录与踩坑总结

• 接口与函数设计约定

示例：

• 2026-05-08_需求与业务约束_用户登录模块.md

• 2026-05-09_修改记录_订单接口参数调整.md

• 2026-05-10_编码规范与写法约定_Go语言命名.md

2.3 文件内容规范

• 仅保留对应维度内容，不混入其他维度信息

• 关键信息加粗（如强制约束、禁止写法、核心约定），提升向量检索精准度

• 避免冗余：每个文件控制在300-800字，聚焦核心信息，不堆砌无效内容

• 可手动编辑：生成后若有遗漏/错误，可直接修改Markdown文件（人可干预，灵活调整）

技能3：自制向量jcemb工具使用（核心联动）

核心说明：自制向量CLI工具统一命名为「jcemb」，以下为工具专属命令及使用规范，所有操作均在项目根目录执行。

3.1 工具触发时机

• 非实时触发：无需每次生成记忆文件就执行，攒够3-5个文件或每天空闲时执行一次

• 手动触发：在项目根目录执行jcemb扫描命令，扫描memory目录下所有Markdown文件（命令详见3.2.1）

• 自动触发（可选）：配置定时任务，每天固定时间自动执行jcemb扫描与向量化命令

3.2 工具核心操作（含专属命令）

jcemb version 检查工具是否安装

Mac下安装

brew install bspiritxp/tap/jcemb

Windows安装

scoop bucket add bspiritxp https://github.com/bspiritxp/scoop-bucket.git
scoop install jcemb

3.2.1 扫描目录向量化命令

• 命令格式：jcemb scan \<path\> \-r

• 参数说明：

  • <path>：必选参数，指定需要扫描的记忆文件目录（默认填写项目根目录下的memory目录，即./memory）

  • -r：可选参数，递归扫描指定目录下的所有子目录及.md文件，确保无遗漏

• 实操示例：jcemb scan \./memory \-r（递归扫描当前项目memory目录下所有记忆文件，执行向量化处理）

3.2.2 检索查询命令

• 命令格式：jcemb query \&\#34;\<query text\>\&\#34; \-\-path \<path\> \-\-json -u

• 参数说明：

  • &#34;<query text>&#34;：必选参数，填写用户当前提问/检索关键词（需用双引号包裹，支持自然语言提问）

  • --path <path>：必选参数，指定向量检索的目录路径（与扫描时的path一致，默认./memory）

  • --json：可选参数，指定检索结果以JSON格式输出，便于AI Agent解析读取上下文

  • -u: 可选参数，根据文件路径去重后的结果。

  • --rerank bm25: 可选参数, 对召回结果进行BM25重排。

• 实操示例：jcemb query \&\#34;用户登录模块的业务约束\&\#34; \-\-path \./memory \-\-json（检索memory目录下与用户登录模块业务约束相关的记忆，以JSON格式返回结果）

3.2.3 工具核心功能说明

• 扫描功能：通过jcemb scan \<path\> \-r命令，自动遍历指定目录及子目录，识别所有.md格式记忆文件，跳过非记忆文件

• 向量化功能：读取每个Markdown文件内容，执行向量化处理，生成对应向量数据

• 入库功能：将向量数据统一存入指定向量库（无需关联代码，仅存储记忆文本对应的向量）

• 更新功能：再次执行扫描命令时，自动识别新增/修改的记忆文件，仅对变动文件重新向量化，避免重复处理

• 检索功能：通过jcemb query命令，根据用户提问检索相关记忆向量，快速召回匹配的记忆文件

3.3 工具使用注意事项

• 执行扫描命令前确认：memory目录下无无效/错误Markdown文件，避免向量库存入垃圾数据

• 向量库维护：定期清理过期记忆（如项目废弃、无效约定），避免向量库过大影响检索速度

• 异常处理：若jcemb工具执行失败，检查文件格式（确保是标准Markdown）、目录权限、向量库连接状态，同时核对命令格式是否正确

• 命令注意：路径填写需准确，检索时query文本需用双引号包裹，避免参数识别错误

技能4：新对话上下文召回（痛点解决核心）

4.1 召回流程（固定）

1. 新开对话/继续开发时，先触发自制向量jcemb工具，执行检索命令（jcemb query \&\#34;\<query text\>\&\#34; \-\-path \./memory \-\-json）

2. jcemb工具根据用户当前提问，检索向量库中相关的历史记忆向量，召回Top3最相关的记忆文件

3. 将召回的记忆文件内容（结构化Markdown，若开启--json则解析JSON结果），自动带入AI Agent上下文

4. Agent基于召回的历史约定、需求、约束，结合当前提问，直接给出方案，无需重新沟通、重新检索

4.2 检索优化技巧

• 提问时带上「模块/主题」关键词（如jcemb query \&\#34;修改用户登录接口，之前的业务约束是什么\&\#34; \-\-path \./memory \-\-json），提升召回精准度

• 若召回结果不准确，检查记忆文件内容是否规范、向量库是否已通过jcemb scan命令更新最新记忆，同时核对检索命令参数是否正确

• 多维度召回：若当前提问涉及多个维度，执行jcemb检索命令时，在query文本中补充多维度关键词，工具自动检索对应多个维度的记忆文件，整合上下文

技能5：异常处理与优化

5.1 常见异常及解决方法

• 记忆文件检索不到：检查jcemb query命令是否正确、向量库是否已通过jcemb scan命令更新、记忆文件是否存入指定path目录（默认./memory）

• 召回记忆不准确：优化记忆文件内容（剔除冗余）、调整jcemb检索关键词、确保Prompt生成的内容语义清晰，同时确认扫描命令已执行并更新向量库

• jcemb工具执行失败：检查文件权限、向量库连接、Markdown文件格式（避免语法错误），核对命令格式（如path参数、query双引号、-r/--json参数使用）

• 记忆文件冗余：定期清理无效/过期记忆，合并重复内容的文件，减少jcemb扫描和检索的负担

5.2 效率优化建议

• 批量总结：多个短对话可合并，按维度批量生成记忆文件，减少jcemb scan命令的执行次数

• 标签补充：可在记忆文件开头添加模块标签（如【用户模块】），提升jcemb检索速度和精准度

• 向量库优化：定期对向量库进行压缩、去重，提升jcemb query命令的检索响应速度

三、技能落地流程（精简版）

1. 开发对话结束 → 选择对应维度 → 使用Prompt生成结构化Markdown记忆文件

2. 按命名规范，将记忆文件存入项目memory/目录

3. 攒够记忆文件后，执行jcemb扫描命令：jcemb scan \./memory \-r，批量向量化并入库

4. 新开对话 → 调用jcemb检索命令（如jcemb query \&\#34;查询关键词\&\#34; \-\-path \./memory \-\-json）检索历史记忆 → Agent带入上下文 → 直接开发/修改，无需重复沟通

四、注意事项

• 不做代码向量化，代码检索仍依赖IDE原生功能（全局搜索、跳转定义），聚焦记忆管理，降低jcemb工具的使用成本和维护难度

• 记忆文件优先保证「准确、简洁」，避免冗余信息影响jcemb检索精准度

• 定期维护memory目录和向量库，避免垃圾数据堆积，确保jcemb scan和jcemb query命令的执行效率

• 所有操作遵循规范，确保jcemb向量检索时语义统一，提升上下文召回效果；jcemb命令需严格按照格式执行，避免参数错误