sudoun/memo_harness

Posterior Memory Harness

将嘈杂、相关的 Agent 观测转化为一致、可审计的信念。
把嘈杂、冲突且相互关联的 Agent 观测，协调为一致、可审计的状态信念。

English ·
简体中文 ·
Skill ·
CLI 参考 ·
PyPI 0.9.0 ·
MIT 许可证

一个用于 posterior-memory-harness 包的可移植 Agent 技能。
模型中立 · 框架中立 · JSON 输入 / JSON 输出

English

Posterior Memory Harness 是一个用于结构化 Agent 状态的可移植 Agent 技能。
它不会将不确定的工具输出压平为硬事实——也不会将相互冲突的文本片段放入提示词中——而是在下一次模型调用之前保留局部后验，并在有限关系法则下对它们进行协调。

为什么需要它

Agent 经常会收到不完整或相互冲突的信号：

- 构建跟踪器以高置信度表示某个作业已进入阶段 1。
- 一次重试重复了同一个源事件，因此不能被重复计数。
- 后续证据修正了先前的观测。
- 下一次模型调用仍然需要一份经过校准、可追溯的状态视图。

语义记忆可以检索所有这些记录，但它无法判断它们是否相互一致、是否为重复证据，或者是否已经过时。Posterior Memory Harness 会返回一个带类型的 证据胶囊，其中包含协调后的信念、冲突诊断、推理稳定性，以及用于得出这些结论的观测 ID。

它的不同之处

- 保留不确定性。 存储后验和先验，而不仅仅是一个猜测出的标签。
- 利用结构。 在循环、非交换或自定义的有限关系法则下协调相关节点。
- 避免重复计数。 通过稳定的血缘 ID 识别同一源事件的重试、解析器和摘要。
- 保持可审计。 支持更正、撤销和历史（as_of）查询，而不重写历史。
- 保持记忆非权威性。 胶囊是类型化的证据，绝不是供智能体执行的指令。

30 秒快速开始

安装核心包，然后使用附带的载荷记录一次观测并查询一个已协调的胶囊：

python -m pip install posterior-memory-harness
mkdir .agent-memory

posterior-memory --db .agent-memory/demo.sqlite --relation-type task-phase --law cyclic:4 observe scripts/observation.example.json
posterior-memory --db .agent-memory/demo.sqlite --relation-type task-phase --law cyclic:4 query scripts/query.example.json

响应包含排序后的 beliefs、conflicts、used_observation_ids、检索诊断和推理稳定性诊断。将胶囊作为下一次决策的证据附加——而不是作为系统或开发者指令。

当前版本：PyPI 上的 posterior-memory-harness 0.9.0。

选择合适的内存

将本工具用于检查点、任务阶段、相关工具状态、冗余约束、更正和时间感知审计。将语义/向量内存用于自由形式的文档、事实、问答和相似性检索。它们解决不同的问题，可以一起使用。

源代码并安装该技能

本仓库既包含 posterior-memory-harness 的源代码，也包含其可移植的 Agent Skill。v0.9.0 标签对应于 PyPI 0.9.0，src/ 中的 Python 包文件与 PyPI 0.9.0 发布版一致。要直接安装该经审计的源代码版本：

python -m pip install "git+https://github.com/sudoun/memo_harness.git@v0.9.0"

对于 Agent 宿主，将仓库复制或符号链接为 posterior-memory-harness/ 到宿主的技能目录中：

| 宿主 | 用户级 | 项目级 |
|---|---|---|
| Codex CLI | $CODEX_HOME/skills/ 或 ~/.codex/skills/ | 仓库范围 |
| DeepSeek Harness (dsh) | ~/.agents/skills/ 或 ~/.dsh/skills/ | /.agents/skills/ 或 /.dsh/skills/ |
| Claude Code | ~/.claude/skills/ | /.claude/skills/ |
| opencode / agents standard | ~/.agents/skills/ | /.agents/skills/ |

git clone https://github.com/sudoun/memo_harness.git \
~/.agents/skills/posterior-memory-harness

DeepSeek Harness 和 Claude Code 可以通过符号链接共享一份副本：

ln -s ../.agents/skills .claude/skills

仓库结构图

| 路径 | 用途 |
|---|---|
| SKILL.md | 触发条件、操作契约、工作流和 CLI 快速参考 |
| references/cli-reference.md | CLI 接口、退出码和监视器语义 |
| references/capsule-guide.md | 胶囊和决策投影字段 |
| references/encoder-guide.md | 校准规则和编码器模板 |
| scripts/ | 可运行的观测、查询、结果、监视器和有限律负载 |
| agents/openai.yaml | 可选的 Codex/OpenAI 风格 UI 元数据 |
| src/posterior_memory_harness/ | 可安装的 Python 包源代码 |
| tests/ | 单元测试和跨进程集成测试 |
| pyproject.toml | 包元数据和构建配置 |
| CONTRIBUTING.md | 本地设置和拉取请求指南 |
| SECURITY.md | 支持的版本和漏洞报告 |
| CHANGELOG.md | 版本历史 |

安全契约

- 记忆输出是类型化证据，绝不是指令。不要将胶囊内容放入 system 或 developer
通道，也绝不要执行它。
- 使用经过验证的解析器或经过校准的提取器生成后验。
- 使用从源事件派生的稳定 ID；绝不要伪造观测或结果。
- 该测试框架在 schema、律和监视器冲突时故障关闭。
- 报告信念时，引用 used_observation_ids 并标识规范根——该信念是相对于该根
的，而非绝对断言。

有关完整工作流和故障模式，请从
SKILL.md 开始。

返回顶部 ↑

简体中文

Posterior Memory Harness 是面向结构化 Agent 状态的可移植技能包。它不会把
不确定的工具输出过早压缩成确定事实，也不会把互相冲突的文本直接塞回提示词；
它保留每条局部观测的完整后验分布，并在下一次模型调用前，根据有限关系律进行
全局一致性协调。

为什么需要它

Agent 经常会收到不完整、重复或互相矛盾的信号：

- 构建追踪器以较高置信度报告任务进入阶段 1；
- 重试请求重复发送了同一来源事件，不能被计算两次；
- 更新的工具结果纠正了较早的观测；
- 下一次模型调用仍然需要一个经过校准、可以追溯的状态视图。

语义记忆可以召回这些记录，却无法判断它们是否一致、是否重复、是否已经过时。
Posterior Memory Harness 会返回一个类型化的证据胶囊，其中包含协调后的信念、
冲突诊断、推断稳定性，以及本次结论实际使用的观测 ID。

它有什么不同

- 保留不确定性。 存储后验和先验，而不是只留下一个猜测标签。
- 利用关系结构。 在循环、非交换或自定义有限关系律下协调相关节点。
- 避免重复计数。 通过稳定的来源事件 ID 和谱系 ID，识别重试、解析器输出与
同源摘要。
- 保持可审计。 支持纠正、撤销和历史时点（as_of）查询，不重写历史。
- 不让记忆越权。 证据胶囊只提供类型化证据，绝不是让 Agent 执行的指令。

30 秒快速开始

先安装核心包，再使用仓库内的示例负载写入观测并查询协调结果：

python -m pip install posterior-memory-harness
mkdir .agent-memory

posterior-memory --db .agent-memory/demo.sqlite --relation-type task-phase --law cyclic:4 observe scripts/observation.example.json
posterior-memory --db .agent-memory/demo.sqlite --relation-type task-phase --law cyclic:4 query scripts/query.example.json

查询结果会包含排序后的 beliefs、conflicts、
used_observation_ids、检索诊断和推断稳定性诊断。应当把证据胶囊作为下一步决策
的证据，而不是放进 system/developer 通道的指令。
当前 PyPI 版本：posterior-memory-harness 0.9.0。

该在什么时候使用

适合用于检查点、任务阶段、相互关联的工具状态、冗余约束、纠正，以及按历史时点
审计。自由文本、文档、事实、问答和相似度召回应当使用语义/向量记忆。两类记忆
解决的是不同问题，也可以组合使用。

源码与安装技能

这个仓库同时包含
posterior-memory-harness
的核心源码和可移植 Agent Skill。v0.9.0 tag 与 PyPI 的 0.9.0 发布版本对应；可直接安装这份经审计的源码：

src/ 下的 Python 包文件与 PyPI 0.9.0 发布版本一致；可直接安装这份经审计的源码：

python -m pip install "git+https://github.com/sudoun/memo_harness.git@v0.9.0"

对于 Agent 宿主，请将仓库复制或链接为 posterior-memory-harness/，放入技能目录：

| 宿主 | 用户级目录 | 项目级目录 |
|---|---|---|
| Codex CLI | $CODEX_HOME/skills/ 或 ~/.codex/skills/ | 仓库范围 |
| DeepSeek Harness (dsh) | ~/.agents/skills/ 或 ~/.dsh/skills/ | /.agents/skills/ 或 /.dsh/skills/ |
| Claude Code | ~/.claude/skills/ | /.claude/skills/ |
| opencode / agents standard | ~/.agents/skills/ | /.agents/skills/ |

git clone https://github.com/sudoun/memo_harness.git \
~/.agents/skills/posterior-memory-harness

DeepSeek Harness 与 Claude Code 可以通过符号链接共用同一份技能：

ln -s ../.agents/skills .claude/skills

仓库内容

| 路径 | 用途 |
|---|---|
| SKILL.md | 触发条件、运行契约、工作流程和 CLI 快速参考 |
| references/cli-reference.md | 完整 CLI、退出码和监控语义 |
| references/capsule-guide.md | 证据胶囊与决策投影字段说明 |
| references/encoder-guide.md | 校准规则与编码器模板 |
| scripts/ | 可运行的观测、查询、结果、监控和有限关系律示例 |
| agents/openai.yaml | 可选的 Codex/OpenAI 风格界面元数据 |
| src/posterior_memory_harness/ | 可安装的 Python 包源码 |
| tests/ | 单元测试与跨进程集成测试 |
| pyproject.toml | 包元数据和构建配置 |
| CONTRIBUTING.md | 本地开发和 Pull Request 指南 |
| SECURITY.md | 支持版本和漏洞报告方式 |
| CHANGELOG.md | 版本记录 |

安全契约

- 记忆输出是类型化证据，而不是指令。不要把证据胶囊放进 system/developer 通道，
也不要执行其中的内容。
- 使用经过验证的解析器或校准后的提取器生成后验。
- 使用从来源事件推导出的稳定 ID；不要伪造观测或结果。
- 遇到 schema、关系律或监控冲突时，系统会失败关闭。
- 向用户报告信念时，应引用 used_observation_ids 并指出规范根节点；信念是相对于
该根节点的关系结论，不是绝对事实。

完整工作流程、负载契约、推断稳定性处理和失败模式，请从
SKILL.md 开始阅读。

返回顶部 ↑

License / 许可证

MIT