Pi Hermes Memory

Pi Hermes Memory 是一个 Pi Coding Agent 扩展，为 Pi 增加跨会话持久记忆、会话搜索、后台学习、过程型技能和技能治理能力。安装后，代理可以把稳定事实写入本地存储，在后续会话按需搜索，而不是把所有历史内容塞进系统提示词。

当前包版本: 0.7.15

快速开始

pi install npm:pi-hermes-memory

从 GitHub 安装:

pi install git:github:chandra447/pi-hermes-memory

本地开发或直接运行当前 checkout:

pi -e ./src/index.ts

常用初始化命令:

/memory-index-sessions
/memory-sync-markdown
/memory-interview
/learn-memory-tool

这个扩展做什么

能力	当前行为
持久记忆	将用户画像、全局记忆、项目记忆和失败经验写入本地 Markdown 与 SQLite 搜索库；replace 的旧值在 SQLite 保留为 superseded 历史，项目与全局/组织层之间可显式 promote/demote
默认低 token 注入	默认 memoryMode: "policy-only"，系统提示词只注入记忆使用策略，具体内容由工具按需搜索
项目级记忆	基于 cwd 或配置识别项目，在平面 Markdown 文件中写入真实项目归属并默认隔离
会话搜索	/memory-index-sessions 建索引后，LLM 可用 session_search 搜索历史 Pi 会话
记忆搜索	memory_search 默认使用 FTS；显式配置 embedding provider 后，在既有 scope 内执行 FTS + 进程内余弦混合检索
后台学习	按用户轮次或工具调用数触发后台 review，保存值得复用的事实和项目技能
修正捕获	用户纠正代理时可立即触发保存，避免反复犯同一类错误
自动整理	记忆接近容量时先在同 scope 内离线预聚类近重复，再由子进程按组合并、替换或压缩
技能系统	通过 Pi 原生 SKILL.md 保存过程型知识，支持全局和项目两个作用域
技能治理	记录真实 skill.use 证据，支持项目技能晋升、降级、隐藏和统计
内容扫描	记忆和技能写入前经过扫描，拦截密钥、prompt injection、角色劫持和隐形字符等风险

数据目录

agentRoot 默认是 ~/.pi/agent，也可以通过环境变量整体切换:

PI_CODING_AGENT_DIR=/custom/pi-agent pi

默认布局:

路径	用途
<agentRoot>/hermes-memory-config.json	配置文件
<agentRoot>/pi-hermes-memory/MEMORY.md	全局代理记忆
<agentRoot>/pi-hermes-memory/USER.md	用户画像和偏好
<agentRoot>/pi-hermes-memory/failures.md	失败、修正、洞察、约定、偏好和工具怪癖
<agentRoot>/pi-hermes-memory/sessions.db	SQLite 会话索引、记忆 FTS、普通 BLOB 嵌入向量与 supersede 历史、技能统计（含 skill_load_daily；skill_load_events 保留历史数据，只读不再写入；按 skillGovernance.loadEventRetentionDays 机会式 TTL 清理，见下文）和治理状态
<agentRoot>/pi-hermes-memory/skills/<slug>/SKILL.md	扩展管理的全局技能
<agentRoot>/projects-memory/MEMORY.md	项目级记忆平面文件；每个受管条目通过 project=<项目名> 元数据记录真实归属
<agentRoot>/projects-memory/<project>/skills/<slug>/SKILL.md	项目级技能
<agentRoot>/sessions/	Pi 会话 JSONL，供会话索引读取

如果配置了 memoryDir，SQLite 文件实际位于 <memoryDir>/sessions.db。

如果从旧版本升级，扩展会在启动时尽力迁移旧目录:

旧位置	新位置
<agentRoot>/memory	<agentRoot>/pi-hermes-memory
<agentRoot>/pi-hermes-memory/skills/*.md	<agentRoot>/pi-hermes-memory/skills/<slug>/SKILL.md
<agentRoot>/<project>/MEMORY.md	<agentRoot>/projects-memory/MEMORY.md
<agentRoot>/projects-memory/<project>/MEMORY.md	<agentRoot>/projects-memory/MEMORY.md

项目记忆合并完成后，来源文件会被改名为 MEMORY.md.migrated（内容保留），避免下次启动重复合并、复活已在平面文件中删除的条目；合并时会按来源目录补写真实 project 元数据，已有归属保持不变。/memory-sync-markdown 不会把 retired 来源导回 SQLite；它逐条读取 projects-memory/MEMORY.md 的归属字段，以真实项目名回填和对账。无归属项目条目会保留在 Markdown 中，但跳过 SQLite 并报告 warning/skipped，不会被自动改写或淘汰。

项目条目元数据格式为:

正文 <!-- created=2026-07-29, last=2026-07-29, project=my-project -->

全局 MEMORY.md、USER.md 不写 project 字段。failures.md 在项目会话中写真实归属；非项目会话产生的无归属 failure 是全局失败，对所有项目可见。 failure 的容量统计、FIFO 淘汰和自动整理输入只包含当前项目条目与无归属全局 failure；其他项目的 failure 不会被当前会话自动整理或删除。该维护边界不受 projectMemorySharing 影响。

记忆模型

默认模式是 policy-only。启动时系统提示词会得到一段 <memory-policy>，告诉代理什么时候调用 memory_search、session_search、memory 和 skill。完整 Markdown 记忆默认不注入系统提示词，这样可以减少首轮 token 占用，也能避免旧记忆直接覆盖当前用户请求。

如需兼容旧行为，可以设置:

{
  "memoryMode": "legacy-inject"
}

legacy-inject 会把全局记忆、用户画像、当前可见的项目记忆和近期可见失败记忆用 <memory-context> 边界块注入系统提示词。默认只注入当前项目条目；无归属 failure 作为全局失败注入。即使在这个模式下，当前用户请求、仓库文件和工具输出也应优先于旧记忆。

斜杠命令

命令	用途
/memory-insights	查看当前全局、用户、失败和项目记忆概览
/memory-skills	打开技能管理界面，查看全局、项目和外部加载的技能
/memory-skill-governance	管理项目技能到全局技能的治理状态
/memory-skill-visibility	按项目隐藏、显示或重置全局技能可见性
/memory-skill-stats	查看 resources_discover 记录的技能加载和曝光统计（sinceDays 按 UTC 天粒度对齐）
/memory-review-status	查看当前进程内的后台记忆 review 计数器和最近一次 review 状态
/memory-doctor	只读检查 Markdown/SQLite 漂移、会话索引、嵌入覆盖率，并报告项目×项目及项目×全局的跨 scope 近重复候选；只报告不动作
/memory-consolidate	手动触发全局、用户和项目记忆整理
/memory-interview	通过问答预填用户画像
/memory-learn-skill	让当前代理把近期上下文或来源材料沉淀为项目优先的技能
/memory-switch-project	按真实归属列出各项目条目数和无归属计数；当前项目仍由 cwd 或配置决定
/memory-index-sessions	将历史 Pi 会话导入 SQLite 会话搜索索引
/memory-sync-markdown	将已有 Markdown 记忆回填到 SQLite 记忆搜索库
/memory-preview-context	预览当前会注入系统提示词的记忆策略或 legacy 记忆块
/learn-memory-tool	显示扩展的使用说明和排障提示

skill_load_events 表已改为只读历史留存，不再写入；仅用于回填和核对。已知边界：若回退到旧版后又升级，旧版期间新增的 raw 增量不会再次回填进入 skill_load_daily 聚合统计，但 raw 数据会被完整保留。

每次 resources_discover 写入 skill_load_daily 之后，会机会式检查是否需要清理过期行：距上次清理 ≥24 小时（或从未清理过）才会真正执行一次，skillGovernance.loadEventRetentionDays（默认 180 天）之前的 skill_load_daily、skill_load_events 行会被删除；loadEventRetentionDays: 0 完全禁用清理（连清理时间戳都不更新）。每张表单次最多删除 skillGovernance.loadEventCleanupBudget（默认 500）行，避免长事务；一次删不完的部分留到下一次到期的 24 小时窗口继续删，但当前这一轮仍会记录清理时间，防止繁忙项目在同一天内反复触发删除。清理失败会被隔离并仅打印警告，不影响 resources_discover 主流程；不会在扩展启动路径上运行。skill_usage_events 永远不受清理影响。

/memory-skill-governance 支持这些动作:

/memory-skill-governance status
/memory-skill-governance curate
/memory-skill-governance explain <skill_id>
/memory-skill-governance promote <skill_id>
/memory-skill-governance demote <skill_id>
/memory-skill-governance restore <skill_id>
/memory-skill-governance clear <skill_id>
/memory-skill-governance reload

/memory-skill-visibility 支持:

/memory-skill-visibility list [--project <project>]
/memory-skill-visibility hide <global_skill_id...> [--project <project>]
/memory-skill-visibility show <global_skill_id...> [--project <project>]
/memory-skill-visibility reset <global_skill_id...> [--project <project>]

隐藏、显示、晋升、降级或恢复技能后，运行 /memory-skill-governance reload 或开启新会话，Pi 才会刷新技能发现结果。

/memory-skill-governance status 还会附带 Curation Jobs 段，展示当前活跃作业、最近一条作业的状态/原因码与累计 skip 计数。 手动执行 /memory-skill-governance curate 与自动触发的策展共享同一项目级租约；若有正在进行或排队的作业，手动调用会提示稍后重试。僵死作业会先被清理再尝试执行，不会永久阻塞。

LLM 工具

这些工具由扩展注册给代理使用，通常不需要用户手动调用。

工具	主要用途
memory	写入、替换、删除持久记忆，并在当前项目与全局/组织层之间显式移动
memory_search	搜索 SQLite 记忆库
session_search	搜索已索引的历史会话
skill	创建、查看、使用、更新、删除技能，并管理项目级全局技能可见性
memory_skill_stats	只读查询技能加载统计、治理状态和晋升状态
skill_governance_curate	后台或子会话用于提交结构化技能治理分类

memory

支持目标:

target	含义
user	用户画像、偏好、沟通风格和长期指令
memory	全局事实、环境信息、跨项目经验
project	当前项目的架构、命令、约定和工作流
failure	失败、修正、洞察、偏好、约定或工具怪癖；项目会话写真实项目归属

支持动作:

action	含义
add	添加新条目；同 scope active 近邻会先返回提示，force: true 可明确越过
replace	用 old_text 匹配并替换已有条目；旧 SQLite 行保留为 superseded 历史
remove	用 old_text 匹配并删除已有条目
promote	用 old_text 将当前项目条目移动到全局/组织层；方向隐含，不传 target
demote	用 old_text 将全局条目移动到当前项目；方向隐含，不传 target

failure 记忆可带 category:

failure, correction, insight, preference, convention, tool-quirk

add 落盘前会全量扫描写入目标的同 scope active own 行（与 FTS 无关），再以保守的 token-set Jaccard 阈值在代码内评分，提示最多返回 3 个近邻。无空格的 Han、Hiragana、Katakana 和 Hangul 内容按 Unicode 码点 bigram 比较，包括增补平面字符；空格词 token 与中英混排同时支持。启用有效 embedding provider 后，如果新内容与候选行都有当前 provider/model 的有效向量，则余弦相似度 >= 0.90 或既有 token 判据任一命中都会拦截；任一侧缺少有效向量时仍只使用原 token 判据。项目写入只检查当前项目 own 行；foreign、无归属项目行、superseded 行和其他 target 都不参与，projectMemorySharing 不会放宽这个写入面。failure 不做近邻拦截。命中时本次不写入，并返回候选正文以及 replace / force: true / 放弃三种行动提示；provider 失败或超时会静默回落，写入不受影响，全程不调用 LLM。

force 只越过近邻提示。精确重复仍先按既有行为返回成功 NOOP，force: true 也不会创建精确副本。

operations 批量写入支持 memory、user、project，每个 add op 也可带 force，但同一批不能混用项目记忆和全局/用户记忆。命中近邻的 add op 会带结构化提示失败，其余 op 继续按部分提交语义执行。容量触发自动整理时，单条 add 与 batch 都会在整理成功、重新加载文件后以新鲜候选视图复检；batch 保留原始 operation 坐标并重新执行顺序模拟，整理新产生的近邻不会绕过拦截。force: true 的 add 不做该近邻复检。

replace 不改变 Markdown 文件契约：MEMORY.md、USER.md 和 failures.md 只保留当前 active 条目。SQLite 会插入新的 active 行，并把旧行的 superseded_by 指向新行、superseded_at 记为当天；连续 replace 可形成 A→B→C 多级链。replace 合并到同 scope 已有相同正文时会指向该 canonical active 行，不产生 active 重复。remove 与 FIFO eviction 仍物理删除对应 active 镜像，不创建 supersede 节点。

promote / demote 是单条目的显式分层移动，不是复制，也不接受 target；operations batch 会明确拒绝这两个 action，并提示改为单发。两者都要求活动项目：promote 从项目层定位源，匹配范围与 project replace 完全相同（默认仅 own；projectMemorySharing: true 时可显式匹配可见 foreign 条目）；demote 从无归属的全局 memory 层定位源，并写入当前项目。user 和 failure 不参与。容器部署中全局层就是组织层，因此同一动作也覆盖项目↔组织的分层。

文件移动固定按防丢失顺序执行：先在目标 store 的写锁内写目标，再在源 store 的写锁内精确删除先前定位的源身份。目标正文不变，created 保留，last 刷新为当天；promote 后去掉 project=，demote 后写入当前项目归属。正常完成后同文 active 条目只存在于目标层。若目标已写而源删除失败，工具返回成功结果和明确 warning，并保留可能的双层副本；进程崩溃也至多留下这类可恢复双存窗口，不会因执行顺序造成两层皆无。可用 /memory-doctor 和 /memory-sync-markdown 检查并再次处置。

目标层判定与 add 同构：精确同文优先退化为 merged，只删除源文件条目，并在 SQLite 把源 active 行 supersede 到目标 canonical 行；canonical 的 created 保持不变，Markdown last 与 SQLite last_referenced 都刷新为当天。非同文近邻会阻断且返回最多三个目标层候选，force: true 只越过该近邻提示。近邻范围是目标层 active own 集（promote 为全局集，demote 为当前项目 own 集），只使用 token 判据和双方已有的当前模型向量，移动路径从不调用 embedding provider。目标层容量、FIFO 和 auto-consolidate 行为也复用该层 add；整理成功重载后会再次检查目标近邻，不能绕过单调复检。

常规移动的 SQLite 镜像不会 delete+insert：它在源行上就地更新 project、保留行 id、既有 supersede 祖先指向以及 embedding/embedding_model，同步 created 并刷新 last_referenced。memories_au 会照常维护 external-content FTS；正文未变。Markdown 始终是权威源，镜像更新失败只附带 warning，不回滚已经安全落盘的文件移动。

自动整理

容量触发和 /memory-consolidate 使用相同的整理输入边界：全局/用户只处理各自 scope，项目只处理当前项目 own 条目，failure 只处理当前项目与无归属全局 failure；projectMemorySharing 不会扩大自动维护范围。父进程在启动整理子进程前，以纯代码对同 scope 条目做 O(n²) 近重复预聚类：

• 双方都有当前 provider/model 的已存有效向量时，用进程内余弦，>= 0.82 进入同一候选簇。
• 任一侧没有当前有效向量时，复用写入近邻的保守 token-set Jaccard/CJK Unicode 码点 bigram 判据。
• 相似边组成连通分量；多条分量按“近重复簇”呈现，单例归入“未分组”。没有任何簇时，条目正文与 § 分隔保持原格式。

例如子进程可能看到：

[Near-duplicate cluster 1]
项目构建命令要求每次代码合并之前运行完整类型检查
§
项目构建命令要求每回代码合并之前运行完整类型检查

[Ungrouped entries]
发布前确认版本号

聚类只结构化输入，不强制子进程决策；提示词要求优先组内合并、跨组慎并，未分组仍按原整理规则处理。实际落盘继续调用既有 memory tool 的 replace/add/remove 路径，因此 replace 会保留 supersede 链，身份唯一、近邻复检和 batch generation/operation 坐标守卫均不变。

整理全路径不会调用 embedding provider，也不会生成或回填向量。 它只读取 SQLite 中已经存在且匹配当前模型的向量；provider 关闭、数据库缺失或条目没有有效向量时仍可用 token 判据离线整理。

memory_search

memory_search 自动绑定运行时当前项目。默认 projectMemorySharing: false 时，只返回当前项目行和 project IS NULL 的全局行；failure 因而是当前项目 + 全局失败。设置 projectMemorySharing: true 后，搜索可返回全部项目，但任何新写入仍记录真实项目归属。

参数	含义
query	搜索词或自然语言查询
target	可选，memory、user 或 failure
category	可选，仅用于失败类分类
limit	默认 10，最大 20
include_superseded	默认 false；true 时同时返回 superseded 历史，并标出 superseded_by 目标和日期

默认搜索和统计只计算 superseded_by IS NULL 的 active 行；include_superseded 只叠加历史可见性，不改变当前项目/global/sharing 的 scope 谓词。/memory-sync-markdown 回填和对账也只比较 active 行：历史不会因 Markdown 中不存在而被删除，也不会被当成缺失事实重新导入。/memory-doctor 的一致性比较使用 active 行，并在每个 target 旁单列 superseded 数量。

embedding 默认完全关闭，此时 memory_search 直接走原 FTS 路径，结果和格式不变。显式配置并成功读取 API key 后，检索流程如下:

1. 先应用现有 current-project/global/sharing、target、category、active/include_superseded 谓词，得到候选集；向量排序永远不会越过该边界。
2. 查询文本生成向量；本次 scope 内没有当前模型有效向量的候选，最多批量回填 16 条。失败项保持 NULL，以后搜索可再次机会性回填，不做启动期全量任务。
3. FTS 命中序与候选集余弦相似序用 RRF（k=60）融合；没有向量的行仍可通过 FTS 召回。

因此 projectMemorySharing: false 时，项目 A 不会因为语义相似召回项目 B 的行；failure、global 和 superseded 的可见性也仍由原谓词决定。查询向量失败、网络失败、超时或部分条目失败都会静默降级：查询回到 FTS-only，成功的记忆写入照常完成，失败向量留空。向量模型标识是 openai-compatible/<model>；行上的 embedding_model 与当前标识不全等时按 NULL 处理，并在后续搜索中机会性重嵌。

向量以 Float32Array 的普通 SQLite BLOB 保存，余弦在 JS 进程内计算。本实现不加载 sqlite-vec、ONNX runtime 或其他原生向量扩展，也没有为 embedding 增加 npm 依赖。

/memory-doctor

/memory-doctor 保持只读，并在既有目录、Markdown/SQLite 一致性、active/superseded、嵌入覆盖率和会话索引段之间新增 Cross-scope near-duplicate candidates (read-only) 段。这个分析是默认项目隔离之外的诊断视图，只读取全库 active target=memory 行：

• 项目 A × 项目 B 命中时报告“升级候选：或属组织层通用知识”。
• 项目 × 全局命中时报告“疑似重复”，建议人工判断去其一，或把不适合全局的知识下沉到项目。
• user、failure、同 scope 对和 superseded 历史不参与。

判据与整理预聚类一致：双方有当前模型的已存有效向量时使用余弦 >= 0.82，否则使用既有 token/Jaccard/CJK bigram 判据；doctor 同样不会调用 provider 或回填向量。扫描前只为每行计算一次 token 集并引用一次当前有效向量，随后最多比较 250,000 个跨 scope 对；达到预算时停止并明确提示结果可能不完整。每个候选列出两个 scope、截断后的条目摘录、cosine/token 来源、相似度和建议方向，计数明确表示已扫描对中的总检出数；报告最多渲染前 50 条，超出时明确提示截断。完整扫描的空结果显示 无跨 scope 近重复；预算早停且零命中时只说明已扫描范围未发现，未扫描部分保持未知。

Cross-scope near-duplicate candidates (read-only)
Total candidates: 2 (detected in scanned pairs)
1. project:service-a x project:service-b [token=1.000]
   suggestion: 升级候选：若当前项目条目已证明组织内普适，用 memory promote 上移。
2. project:web x global [cosine=0.934]
   suggestion: 疑似重复：可用 memory promote 合并到全局，或用 demote 将仅属当前项目的全局条目下沉。

当数据量触发资源边界时，同一段会附加：

已达比较预算，结果可能不完整（708 行/250000 对上限；已比较 250000 对）
候选输出已截断：显示前 50 条，共检出 250000 条。

该段只报告不动作：doctor 不会自动改写条目。人工确认方向后，可单独调用 memory 的 promote / demote action 处置；项目×项目候选需先切换到要上移条目所属的当前项目。

session_search

默认 sessionSearch.variant 是 legacy，参数为 query、project、role、limit。在设置 sessionSearch.variant: "anchors" 后，工具改为接收一个 Markdown 请求，返回 JSONL 源文件范围锚点。

skill

支持动作:

create, view, use, patch, update, edit, delete, write_file, remove_file, visibility

关键规则:

规则	当前行为
create 必须传 scope	global 用于可迁移流程，project 用于依赖当前仓库路径、脚本、架构或发布方式的流程
view 是只读	只查看或列出技能，不记录真实使用
use 会记录使用证据	项目技能晋升依赖主会话里的真实 skill.use
结构化写入优先	推荐传 when_to_use、procedure_steps、pitfalls、verification_steps
支持文件有白名单	write_file 和 remove_file 只能操作 references/、templates/、scripts/、assets/ 下的支持文件
子会话限制更严	子 prompt 只能查看或改写项目技能，不能 use、delete、visibility 或创建全局技能

配置

配置文件默认位于:

~/.pi/agent/hermes-memory-config.json

完整字段示例:

{
  "memoryMode": "policy-only",
  "memoryPolicyStyle": "full",
  "memoryPolicyCustomText": "<memory-policy>Custom policy text.</memory-policy>",
  "memoryCharLimit": 5000,
  "userCharLimit": 5000,
  "projectCharLimit": 5000,
  "projectMemorySharing": false,
  "nudgeInterval": 10,
  "reviewRecentMessages": 0,
  "reviewEnabled": true,
  "reviewSkillsEnabled": true,
  "flushOnCompact": true,
  "flushOnShutdown": true,
  "flushMinTurns": 6,
  "flushRecentMessages": 0,
  "memoryDir": "pi-hermes-memory",
  "projectsMemoryDir": "projects-memory",
  "projectName": "my-project",
  "sessionSearch": {
    "variant": "legacy"
  },
  "embedding": {
    "provider": "off"
  },
  "llmModelOverride": "provider/model-name",
  "llmThinkingOverride": "medium",
  "memoryOverflowStrategy": "auto-consolidate",
  "autoConsolidate": true,
  "correctionDetection": true,
  "correctionStrongPatterns": ["^actually,\\s+(.+)$"],
  "correctionWeakPatterns": ["^please\\s+remember\\b"],
  "correctionNegativePatterns": ["^never mind\\b"],
  "correctionDirectiveWords": ["remember", "prefer"],
  "failureInjectionEnabled": true,
  "failureInjectionMaxAgeDays": 7,
  "failureInjectionMaxEntries": 5,
  "nudgeToolCalls": 15,
  "skillReviewToolCalls": 10,
  "consolidationTimeoutMs": 60000,
  "skillGovernance": {
    "scopes": {
      "globalSkillsDir": "pi-hermes-memory/skills",
      "projectSkillsDir": "project-skills-root"
    },
    "promotionEnabled": true,
    "promotionMinSameDomainUsages": 3,
    "promotionMinSessions": 2,
    "promotionMinProjects": 1,
    "promotionTaskDomains": [
      {
        "id": "repo-workflow",
        "description": "Repository build, test, and release workflows.",
        "terms": ["build", "test", "release"]
      }
    ],
    "promotionDomainTerms": [],
    "promotionRequireGlobalSafe": true,
    "promotionConflictStrategy": "block",
    "curationTimeoutMs": 60000,
    "curationMaxConsecutiveFailures": 0,
    "autoCurationCooldownMs": 86400000,
    "autoCurationFailureCooldownMs": 3600000,
    "loadEventRetentionDays": 180,
    "loadEventCleanupBudget": 500
  }
}

不需要把所有字段都写进配置文件；缺失字段会使用默认值。上面的 projectName、llmModelOverride、llmThinkingOverride、correction pattern、skillGovernance.scopes.* 和 skillGovernance.curationTimeoutMs 都是覆盖示例，不配置时分别使用 cwd 推导、子进程默认模型/thinking、内置修正规则、默认技能目录和 consolidationTimeoutMs 回落值（示例中的 60000 并非该字段的独立默认值）。

解析和路径规则:

• agentRoot 默认是 ~/.pi/agent；设置 PI_CODING_AGENT_DIR 后，配置文件会从 <agentRoot>/hermes-memory-config.json 读取。
• 配置文件不存在、空文件、JSON 格式错误或读取失败时，整体回退默认配置；未知字段会被忽略。
• 字段类型或枚举值不被识别时，该字段保留默认值。数值字段按源码类型解析，部分阈值字段要求非负数。
• memoryDir 为空或不设置时使用 <agentRoot>/pi-hermes-memory；相对路径按当前 agentRoot 解析，~ 会展开，绝对路径会保留。
• projectsMemoryDir 只接受 agentRoot 下的安全单层目录名；绝对路径必须位于 agentRoot 下，并会规范化为目录名。
• memoryDir 与 projectsMemoryDir 解析 symlink 后的物理根目录必须互不相同（尚未创建的尾段按最深现存祖先解析）；冲突的显式字段会回落默认值并产生启动 warning，/memory-doctor 也会报告仍存在的同根状态。promote/demote 在运行时复用同一物理根身份检查，发现同根会在任何写入或删除前拒绝移动；权限等解析异常保守回落到词法绝对路径判定。
• projectName 不设置时由 cwd basename 推导；空值、.、.. 或包含路径分隔符、,、<、>、换行的值会被忽略。
• embedding.provider 只接受 "off" 或 "openai-compatible"；非法 provider、URL、环境变量名、空 model 或非正 timeout 会使整段 embedding 配置回落到 off。
• openai-compatible 默认 baseUrl 为 https://api.openai.com/v1、默认 model 为 text-embedding-3-small、默认 timeoutMs 为 3000。apiKeyEnv 必须指名一个环境变量；未配置名称或该变量没有值时 provider 视同 off，并由 /memory-doctor 提示。
• autoConsolidate 只用于兼容旧配置；显式设置 memoryOverflowStrategy 时以后者为准。
• skillGovernance.scopes.globalSkillsDir 和 skillGovernance.scopes.projectSkillsDir 的相对路径同样按 agentRoot 解析；配置项目技能根目录后，活动项目技能位于 <root>/<project>/skills。

当前配置字段:

字段	默认值	说明
memoryMode	"policy-only"	"policy-only" 或 "legacy-inject"
memoryPolicyStyle	"full"	"full"、"compact"、"custom"、"none"
memoryPolicyCustomText	未设置	memoryPolicyStyle: "custom" 时使用；空文本会回退到 compact policy
memoryCharLimit	5000	全局 MEMORY.md 字符上限
userCharLimit	5000	USER.md 字符上限
projectCharLimit	5000	每个项目 own 条目的字符上限；foreign/无归属条目不占当前项目预算，也不会被当前项目自动淘汰
projectMemorySharing	false	false 时项目注入、搜索、去重和显式编辑仅限当前项目；true 放宽为跨项目可见/显式编辑，但写入仍归属当前项目，自动整理和淘汰仍仅处理 own
nudgeInterval	10	每多少用户轮次触发后台 review
reviewRecentMessages	0	后台 review 读取的最近消息数，0 表示全部
reviewEnabled	true	是否启用后台记忆 review
reviewSkillsEnabled	true	后台 review 是否可创建或更新项目技能
flushOnCompact	true	compact 前是否 flush
flushOnShutdown	true	会话关闭时是否 flush
flushMinTurns	6	flush 所需最少用户轮次
flushRecentMessages	0	flush 读取的最近消息数，0 表示全部
memoryDir	<agentRoot>/pi-hermes-memory	全局扩展数据目录；相对路径按 agentRoot 解析，旧 <agentRoot>/memory 会迁移到新默认目录
projectsMemoryDir	"projects-memory"	项目记忆根目录名，必须是 agentRoot 下安全单层目录
projectName	cwd 推导	显式项目名，用于项目记忆和项目技能；不安全值会被忽略
sessionSearch.variant	"legacy"	"legacy" 或 "anchors"
embedding.provider	"off"	"off" 或 "openai-compatible"；只有后者且 key 可用时启用混合检索
embedding.baseUrl	"https://api.openai.com/v1"	OpenAI-compatible API 根地址；请求发送到其 /embeddings
embedding.apiKeyEnv	未设置	仅从这个名称指向的环境变量读取 API key；不接受配置文件内明文 key
embedding.model	"text-embedding-3-small"	embedding 模型名，也是行向量有效性标识的一部分
embedding.timeoutMs	3000	单次 embedding 请求超时毫秒数，上限 30000；超时静默降级
llmModelOverride	未设置	子 pi -p 调用使用的模型覆盖；会 trim，空字符串忽略
llmThinkingOverride	未设置	子 pi -p 调用的 thinking 覆盖，支持 off、minimal、low、medium、high、xhigh
memoryOverflowStrategy	"auto-consolidate"	"auto-consolidate"、"reject"、"fifo-evict"
autoConsolidate	true	兼容旧配置；没有 memoryOverflowStrategy 时会映射到新字段，显式策略优先
correctionDetection	true	是否检测用户修正并触发保存
correctionStrongPatterns	内置规则	覆盖强修正正则；空数组表示禁用
correctionWeakPatterns	内置规则	覆盖弱修正正则；空数组表示禁用
correctionNegativePatterns	内置规则	覆盖否定排除正则；空数组表示禁用
correctionDirectiveWords	内置规则	覆盖弱修正后的指令词；空数组表示禁用
failureInjectionEnabled	true	legacy 注入模式下是否注入近期失败记忆
failureInjectionMaxAgeDays	7	注入失败记忆的最大天数
failureInjectionMaxEntries	5	注入失败记忆的最大条数
nudgeToolCalls	15	工具调用数触发后台 review 的阈值
skillReviewToolCalls	10	技能专用后台 review 的工具调用阈值，0 表示关闭独立技能 review
consolidationTimeoutMs	60000	自动整理子进程超时毫秒数
skillGovernance.scopes.globalSkillsDir	<memoryDir>/skills	全局技能目录
skillGovernance.scopes.projectSkillsDir	自动推导	项目技能根目录；相对路径按 agentRoot 解析，活动项目实际路径为 <root>/<project>/skills
skillGovernance.promotionEnabled	true	是否启用项目技能晋升
skillGovernance.promotionMinSameDomainUsages	3	同领域真实 skill.use 次数阈值
skillGovernance.promotionMinSessions	2	真实使用跨会话阈值
skillGovernance.promotionMinProjects	1	真实使用跨项目阈值
skillGovernance.promotionTaskDomains	未设置	可配置任务领域 { id, description?, terms }；id 为小写字母开头的 slug，terms 必须非空
skillGovernance.promotionDomainTerms	[]	全局可迁移领域词
skillGovernance.promotionRequireGlobalSafe	true	晋升是否要求被判定为全局安全
skillGovernance.promotionConflictStrategy	"block"	冲突时 "block" 或 "overwrite"
skillGovernance.curationTimeoutMs	未设置，回落 consolidationTimeoutMs	治理策展（curation）子进程超时毫秒数；不设置时使用 consolidationTimeoutMs，再兜底内置默认值
skillGovernance.curationMaxConsecutiveFailures	0（0 表示不限）	自动策展连续失败次数上限，达到上限时跳过自动触发，0 保持原行为
skillGovernance.autoCurationCooldownMs	86400000（24 小时）	一次成功的自动策展后，到下一次自动触发之间的冷却毫秒数
skillGovernance.autoCurationFailureCooldownMs	3600000（1 小时）	一次策展尝试（无论成败）后，到下一次重试之间的冷却毫秒数
skillGovernance.loadEventRetentionDays	180	skill_load_daily/skill_load_events 的保留天数；0 完全禁用机会式 TTL 清理
skillGovernance.loadEventCleanupBudget	500	每张表单次机会式清理最多删除的行数，避免长事务

技能治理简述

项目技能默认保存在项目作用域。只有在主会话中真实调用 skill 工具的 use 动作，并满足同领域次数、会话数、项目数和安全规则后，才会成为晋升候选。后台 review 可以创建或改进项目技能，也可以提交治理分类，但不会直接创建全局技能、记录使用证据或改动可见性。

skill_governance_curate 提交的策展结果只能影响任务领域词和作用域策略词（同领域证据），永远不能覆盖 skillGovernance.curationTimeoutMs、autoCurationCooldownMs、autoCurationFailureCooldownMs 等时序参数——这些只由静态配置决定，防止策展子进程自我解除限流。

技能统计里的 load/discovery 数字只表示 Pi 在 resources_discover 时看到了这些技能，不代表任务成功，也不代表技能质量。

安全边界

写入记忆和技能前，扩展会扫描以下风险:

风险	处理
API key、token、SSH 私钥等密钥	拒绝保存
prompt injection 和角色劫持文本	拒绝或阻断
隐形 Unicode 字符	拒绝或清理
失败类记忆过宽或过旧	通过分类、搜索和整理降低噪声

搜索结果和旧记忆只是上下文，不是指令。当前用户请求、仓库文件和工具输出始终优先。

embedding API key 只会从 embedding.apiKeyEnv 指名的环境变量读取，不会从配置内接受 key。key 值和完整 baseUrl 不会写入日志、错误、doctor 报告或工具输出。建议为不同环境使用独立的最小权限变量，例如:

{
  "embedding": {
    "provider": "openai-compatible",
    "baseUrl": "https://api.openai.com/v1",
    "apiKeyEnv": "OPENAI_API_KEY",
    "model": "text-embedding-3-small",
    "timeoutMs": 3000
  }
}

开发

npm run check
npm test

本仓库的 TypeScript 入口由 Pi 通过 jiti 直接加载，运行时不需要先编译。