内容
<div align="center">
# Howdex
### 拥有你的人工智能学习循环。
**Howdex 是用于智能体知识的开放验证层。** 它将您最好的 AI 智能体的经验转化为 **已验证的智能体程序**，任何智能体都可以重用，任何团队都可以审计，并且任何模型，无论是前沿还是开放的，都可以执行。
[](LICENSE) []() []()
*一次昂贵的发现。无限次廉价的执行。*
</div>
---
> **Howdex 将执行轨迹转化为可移植的、带有凭据的程序，智能体可以重用，企业可以审计。**
今天，您的智能体是健忘的。智能体解决了棘手的问题 — 恢复了损坏的服务，完成了一个退款和重新预订流程，解决了构建问题 — 但在会话结束时，这种能力就会消失。明天，它从零开始：重新阅读相同的文档，重复相同的死胡同，消耗相同的令牌。您正在为已经知道的事情反复支付前沿价格。
Howdex 解决了这个问题。它观察您的智能体成功，提炼出成功背后的 **可重复的程序**，并附上凭据证明其有效，然后将其作为干净的操作指南交给下一个智能体遵循，确定性地、本地地、便携式地跨所有您使用的模型和框架。
## 结果，衡量
我们不要求您凭信仰接受这一点。在一个 **实际的 Docker Compose 恢复任务** 中，一个新的智能体必须读取五个文件，推断跨文件的配置依赖关系，并修复正确的文件以使服务恢复健康：
| 组别 | 成功率 | 平均尝试次数 |
| --- | --- | --- |
| 新智能体，无记忆 | **35%** (7/20) | 13.00 |
| 相同智能体 + Howdex | **90%** (18/20) | 8.75 |
- **每组 n = 20**，两个组别之间的任务框架完全相同（通过提示哈希验证）。
- **`source_pasted: 0/20`** — 智能体从学习的操作事实中 **重建了修复**。它从未被给予答案。这是真正的知识转移，而不是泄露的解决方案。
- 自己重现：`make bench-docker-n20`
成功率提高了 55 个百分点，尝试次数减少了 33%，仅凭记忆，在一个以前从未见过该任务的模型上。
## 快速入门 — 五分钟即可拥有更智能的智能体
```bash
pip install howdex-ai
# 或者，直接从源码：
pip install git+https://github.com/rossbuckley1990-hash/Howdex.git
```
```python
from howdex import Howdex
mem = Howdex() # 本地 SQLite 存储在 ~/.howdex — 不会离开您的机器
# 1. 捕获成功的运行（包装智能体已经调用的工具）
mem.start_session("恢复损坏的 compose 服务")
mem.log_tool_calls("read_file", {"path": "compose.yml"}, observation="ok")
mem.log_tool_calls("edit_file", {"path": "runtime.env"}, observation="设置 HEALTH_MODE=ready")
mem.log_tool_calls("run", {"cmd": "docker compose up -d --build"}, observation="健康")
mem.end_session("成功")
# 2. 提炼可重用的程序
mem.learn()
# 3. 在新的相关任务中，获取干净、可检查的指导
print(mem.guidance("服务 /health 返回 503 后部署"))
```
**通过 MCP 将其插入任何智能体 — 无需代码：**
```bash
howdex mcp --db ~/.howdex/howdex.db --codex ./codex
```
将 Claude Desktop、Cursor、Windsurf 或任何 MCP 客户端指向它，您的智能体将获得 `remember`、`learn` 和 `guidance` 作为一流工具。
---
## 为什么 Howdex 与众不同
大多数“智能体记忆”存储 **事实**（用户是谁，他们喜欢什么）通过询问 LLM 来总结对话，不透明，不确定，并且锁定在一个云端。Howdex 存储 **实际完成工作的方式** — 并证明这一点。
| | 会话式/事实记忆（Mem0、Zep、Letta） | **Howdex** |
| --- | --- | --- |
| 存储内容 | 事实、偏好、聊天记录 | **可重用的程序 — 如何完成工作** |
| 如何构建 | LLM 总结 | **确定性 — 循环中没有 LLM** |
| 可检查和审计 | 很少 | **是 — 完整的出处 + 凭据** |
| 本地运行，无需模型 | 变化 | **是 — 仅需 numpy 内核** |
| 信任前验证 | 否 | **是 — Codex** |
| 跨模型和云的可移植性 | 变化 | **是 — 您拥有循环** |
Howdex 不是事实记忆的竞争对手，而是 **程序层**，它与事实记忆并存，并实现其他记忆无法实现的功能：使能力 **可重复、可移植和可证明**。
---
## Howdex 为您带来的优势
### 对于开发者
在您已经进行的工具调用周围进行无缝捕获。**5 分钟** 本地设置，一个 MCP 服务器和一个依赖项（`numpy`）。无需云账户，无需操作向量数据库，无需照顾 API 密钥。您的智能体在您接触的每个任务系列上变得更快、更便宜，并且您可以确切地了解它学到了什么，因为没有任何东西是黑箱。
### 对于智能体框架
一次集成，适用于所有堆栈。Howdex 提供适配器，适用于 **LangChain、LangGraph、CrewAI、AutoGen 和 OpenAI Agents SDK**，以及其他框架的通用装饰器和完整的 MCP 服务器。 在您选择的框架中添加程序记忆，无需重写您的智能体。
### 对于团队和企业
Howdex **从设计上讲是本地优先、供应商中立且适合审计的**。程序保留在您的边界内。每个已验证的程序都带有出处、验证器和凭据 — 因此，当智能体回忆“我们如何执行 X”时，您可以证明它来自哪里以及它实际有效。内置治理（`codex lint`、`policy-check`，签名证明）赋予验证层真正的力量。您的操作知识成为一种持久的、您拥有的资产 — 便携式跨模型、框架和云端 — 而不是您从单一提供商租用并在切换时丢失的东西。
### 对于多智能体系统 — 一个共享的、已验证的公地
**Howdex Codex** 是一个开放的、结构化的操作程序目录，具有 CRDT-based 同步功能。一个智能体学习一个程序；其他智能体可以拉取它 — **附带凭据**，因此消费智能体知道是否信任它。智能体队伍停止并行重新发现相同的流程，并开始累积一个共享的、经过验证的知识库。专家智能体发布他们最擅长的程序；通用智能体重用它。公地可检查、受控并由您拥有 — 不是托管的黑箱。
---
## 教师 → 学生经济学
这是不公平的，对您有利。
前沿模型非常出色且昂贵 — 更糟糕的是，他们学到的东西会蒸发并且属于他们自己。Howdex 改变了运行智能体的单位经济学：
1. **用最好的模型学习。** 运行一个前沿模型（**教师**）来完成一个艰难的任务。当它成功时，Howdex 捕获跟踪并提炼出一个 **确定性、已验证的程序** — 附带凭据证明它有效。
2. **发布到注册表。** 该程序进入 Codex：便携、可检查、与模型无关的指导。没有权重，没有提示可以泄露 — 只有操作知识。
3. **用最便宜的模型执行。** 一个更小、更便宜、更开放的模型（**学生**）从注册表中提取已验证的程序并遵循它 — 在该任务上继承教师的硬实力，推理成本仅为一小部分，并且 **内存循环中没有 LLM**。
**只需支付一次前沿价格即可学习。永久重用在成本较低的模型上。** 由于该程序是指导而不是模型特定的权重，因此它适用于不同的模型系列、框架和云端 — 并且由于它有凭据支持，学生知道哪些程序是安全的。跨模型的可移植性是 Howdex 的核心设计目标；正在进行大规模独立传输基准测试，跨模型进行。
---
## Codex — 已验证的智能体程序，您拥有
Codex 强制执行一个规则：**没有证明就没有程序。** 学习后的程序是 `候选`，直到 **可检查的凭据** 显示任务相关的验证器通过后，才变为 `已验证`。每个条目都带有出处、失败尝试记忆（避免什么）、策略和过时元数据以及源排除控制。
```bash
howdex codex lint ./codex # 结构 + 凭据完整性
howdex codex policy-check ./codex # 策略和风险门控
howdex codex verify ./codex # 重新检查验证器证据
```
Codex 不是提示库，也不是执行引擎。**在 Howdex 中，程序是指导，而不是可执行权限** — 消费智能体在其当前环境中验证后才采取行动。正是这种边界使 Howdex 可以安全地用于高风险工作。
---
## 工作原理
```
成功轨迹 ─▶ 学习 ─▶ 规范程序（+ 出处，凭据）
│
按任务相似性检索
│
指导 ─▶ 下一个智能体更快、更便宜地成功
```
确定性规范化将不同措辞的轨迹转换为一个程序。检索是预算和可检查的。指导是操作事实 — 从不粘贴的源代码 — 因此重用证明能力，而不是复制。**可审计的抽象：可选的 LLM 提案，确定性信任。** 可选的、可审计的 LLM 辅助抽象可以提出语义等价，但存储、验证和信任状态始终保持确定性和可逆。
## Howdex 不声称
可信度是产品，因此这里有诚实的界限：
- Howdex 本身并不使自主执行生产就绪；它提供指导和验证元数据，并且消费智能体仍然负责在执行前验证。
- 上面的 Docker 基准测试证明了 **单个程序传输到新的智能体**，而不是在许多独立的轨迹或团队中累积。
- 跨模型的可移植性是一种设计属性；我们不声称跨模型独立证明的实时传输。
- 我们的 AWM 样式比较套件目前在干运行模式下运行；我们不声称干运行 AWM 样式套件结果是实时性能，我们也不声称击败 AWM、WebArena 或 Mind2Web。我们不声称 Howdex 已经击败了 AWM 论文。
- `候选` Codex 条目和未接受的抽象提案未经验证。
## 狗粮 Howdex
Howdex 越来越多地通过其自身的程序记忆循环构建：当我们开发它时，Howdex 捕获构建轨迹，学习程序，并附上通过测试运行的凭据。这些狗粮指标是 **内部证据，仅限内部使用**，它们不是外部用户、采用、市场验证。它们只显示循环在真实的工作负载（我们自己的）上运行。上面的可复制基准测试，而不是这些内部指标，是外部证据。
---
## 安装和文档
```bash
pip install howdex-ai # 或：pip install git+https://github.com/rossbuckley1990-hash/Howdex.git
```
深入探讨生活在 [`docs/`](docs/) 中：架构、Codex 标准和协议、MCP、框架适配器、治理、观测性和 [基准测试方法论](docs/benchmarks.md)。
## 许可证
Apache-2.0. 拥有你的循环。
