PabloTheThinker/hermespace
GitHub: PabloTheThinker/hermespace
为 Hermes Agent 提供只追加的持久化世界模型和便携工作台，让 agent 跨会话积累信念与经验并自主演化。
Stars: 80 | Forks: 5
一个永远生长的持久化 agent 世界。当前轮次的便携工作台。
世界模型 ·
工作台 ·
快速开始 ·
CLI ·
文档 ·
关于
**Hermespace 是一个为 Hermes agents 设计的只追加（append-only）持久化世界。**每一次会话、每一个信念、每一个里程碑、每一次进化都被记录在一个永不裁剪、永不衰减、永不封顶的档案库中。agent 在跨会话的过程中构建了一个关于自身及其环境的不断深化的模型——并且它的存在时间将超越用户。
它不是 [J-Space](https://github.com/anomalyco/j-space)。也不是一个次要的 agent runtime。它是 Hermes 内部一个记住一切的房间。
## 世界模型
一个永远生长的持久化 agent 世界。档案库是事实的唯一来源；缓存永远不具备权威性。
### Archive
```
from hermespace import WorldModel
wm = WorldModel(agent_id="my-agent")
wm.enter() # agent enters the world
wm.add_belief("Fast deploys reduce risk", 0.85, source="observation")
wm.add_belief("Fast deploys reduce risk", 0.85, source="observation") # reinforces
wm.add_landmark("Zero-downtime deploy v2")
wm.set_trait("operations-minded")
wm.set_goal("Improve deploy pipeline", decision="A — automate", plan=["audit", "implement", "verify"])
wm.add_relationship("dev-team", "team", 0.8)
print(wm.render_markdown()) # epoch-aware markdown
wm.evolve() # consolidate, detect patterns, check epoch
```
每一次变更（mutation）都会追加到 `~/.hermespace/worlds/{agent_id}_archive.jsonl` —— 一个永远生长的只追加 JSONL。没有裁剪。没有衰减。没有删除。
条目类型包括：`enter`、`leave`、`landmark`、`belief`、`trait`、`evolution`、`focus`、`epoch_transition`、`resolve`、`relationship`。
### Epochs
agent 的阶段是通过累积的经验来衡量的，而不是现实时间（wall clock）：
| Epoch | 条目数 | 行为 |
|-------|---------|----------|
| **Genesis** ✨ | <5 | 简短的时间线，所有条目均可见 |
| **Growth** 🌱 | 5–24 | 分节标题，对较旧的条目进行总结 |
| **Maturity** 🎓 | 25–99 | 压缩的时间线，从顶级 beliefs 中提取智慧 |
| **Wisdom** 🧠 | 100+ | 受证据把关的智慧，仅保留根深蒂固的 beliefs |
Epoch 的转换会被记录为 `epoch_transition` 档案条目，并会改变世界在 agent context block 中的渲染方式。
### Beliefs
Beliefs 拥有置信度（0–1）和证实计数（corroboration count）。使用相同的陈述调用 `add_belief` 会起到强化作用 —— 置信度增加 +0.1，证实计数递增。`evolve()` 循环会整合来自 `SemanticStore` 的语义笔记，并检测 landmarks 中的重复模式。
### Causal Chains
每个条目都可以通过 `causal_parents` 引用其父条目。`set_goal()` 会链接到最近的时间线条目。`trace_chain()` 会沿档案库向后追溯。
```
# 遍历 chain
focus_entries = wm.archive.query("focus")
chain = wm.trace_chain(focus_entries[-1].id)
# Resolve an outcome
wm.resolve_outcome(lm_entry.id, "success")
```
### Evolution
`evolve()` 循环运行五个阶段：
1. 将语义笔记整合为 beliefs
2. 检测近期 landmarks 中的重复模式
3. 分析关系亲和度趋势
4. 检测里程碑（条目计数阈值，高置信度 beliefs）
5. 从低置信度 beliefs 中生成悬而未决的问题
然后检查 epoch 转换，刷新活跃概念（J-Space hub，最多 25 个），并写入一条 `evolution` 档案条目。
`world_evolve` 脉冲任务（pulse job）每小时运行一次此操作。手动触发：`hs world evolve` 或 `WorldModel.evolve()`。
### Context Injection
每次 `pre_llm_call` 都会注入世界 context：epoch 徽章、活跃概念、智慧（顶级 beliefs）、时间线、脉冲摘要和工作台状态。agent 始终清楚自己处于自身故事中的哪个位置。
### CLI
```
hs world show # render world.md
hs world enter # agent enters the world
hs world leave # agent leaves (session end)
hs world evolve # run evolution cycle
hs world add-belief --statement "..."
hs world add-landmark --event "..."
hs world set-trait --trait "..."
hs world set-goal --goal "..."
hs world search --query "deploy"
hs world archive-stats # count by entry type
hs world timeline --limit 10
hs world resolve --entry-id
--outcome success
hs world trace --entry-id
```
## 工作台
与世界并行，Hermespace 为当前轮次提供了一个工作台（desk）——包含 FOA、dual decode、skills+MEMORY fabric、neural FOA 以及一个 autonomy grid。
| 功能 | 作用 |
|---|---|
| **Focus of Attention** | ≤4 个项目，每轮次单个活跃目标 |
| **Dual Decode** | 为人类提供简短报告；为模型提供高密度 context。绝不将原始注入内容倾倒到聊天频道中。 |
| **Skills + Memory Fabric** | 根据目标对 Hermes 技能进行排名；注入 MEMORY.md / USER.md 的摘录 |
| **Neural FOA** | `HERMESPACE_NEURAL_BACKEND=auto` —— 在线时使用 Ollama embeddings，离线时使用哈希回退 |
| **Autonomy Grid** | 任务（Missions）、视角（lenses）、梦境（dream）、自我对话（self-talk）、技能台（skillbench）、标题/树（title/tree）、访问门控（access gates）。自下而上的设计。 |
| **Pulse Runtime** | 具备工作台感知能力的便携节奏 —— 空闲心跳（idle tick）、梦境（dream）、世界进化（world evolve）、任务脉冲（mission pulse） |
| **Desktop View** | 针对 Hermes Desktop 的侧边栏及全页面插件，配备 Tailscale viewport 和 socket API |
### 快速开始
```
git clone https://github.com/PabloTheThinker/hermespace.git
cd hermespace
./scripts/install_hermes.sh # link skill + plugin
./scripts/smoke_test.sh # expect 9/9
```
```
from hermespace import Workbench
wb = Workbench(agent_id="my-agent", session_id="main")
wb.enter()
r = wb.receive_order("Ship the patch", goal="Ship", decision="A — ship", plan=["implement","test"], say="Shipping.", force=True)
print(r["user_reply"]) # → human
ctx = r["model_context"] # → model (includes world context)
```
### Hermes 插件钩子
| Hook | 发生的动作 |
|---|---|
| `on_session_start` | `WorldModel.enter()` + 进入工作台 + 环境探测 + 注入世界统计数据 |
| `pre_llm_call` | 注入世界 context 块（epoch + 概念 + 智慧 + 时间线 + 脉冲 + 工作台） |
| `on_session_end` | `WorldModel.leave()` + 工作台空闲心跳 |
## 运行原理
```
User message
│
▼
GATE ── trivial? skip ── material? continue
│
▼
ENCODE → DESK → PLAN FOA, load, decision, steps
│
▼
DECODE report (human) + context (model)
│
▼
BROADCAST plugin inject + world context
│
▼
ACT Hermes tools / code / ship
│
▼
SEAL episodic + semantic promote + world evolve
```
状态（本地存储，永不提交）：
```
$HERMESPACE_HOME/memory/hermespace/
ACTIVE.md live desk
hermespace.db turn database
journal/ human-readable logs
workbenches/ per-agent workbench JSON
worlds/ world archive (JSONL) + cache (JSON)
```
## CLI
| 命令 | 用途 |
|---------|---------|
| `hs world show\|enter\|leave\|evolve\|search\|archive-stats` | 持久化世界 |
| `hs turn` | 完整的输入（INPUT） → 输出（OUTPUT）轮次 |
| `hs workbench enter\|order\|idle\|park\|status` | 会话工作台 |
| `hs fabric` / `hs skills` | MEMORY + 排序后的技能 |
| `hs grid mission-add\|lens-set\|think\|dream\|skill-register` | Autonomy grid |
| `hs pulse tick\|daemon\|status` | Pulse runtime |
| `hs neural caps\|eval` | Neural FOA |
| `hs view --serve --port 8764` | Desktop viewport |
| `./scripts/smoke_test.sh` | 健康检查 (9/9) |
## 文档
| 文档 | 内容 |
|-----|----------|
| [`ABOUT.md`](ABOUT.md) | 理念、设计原则、作者 |
| [`INTEGRATION.md`](INTEGRATION.md) | Python · CLI · plugin · 工作台入口 |
| [`skills/hermespace/SKILL.md`](skills/hermespace/SKILL.md) | **Agent 技能**（在 Hermes 中加载） |
| [`FOR_HERMES.md`](FOR_HERMES.md) | 维护者 / 内部测试简报 |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | 如何贡献 |
| [`WORKFLOW.md`](WORKFLOW.md) | GATE → SEAL 阶段 |
| [`SECURITY.md`](SECURITY.md) | 绝不通过 git 发布的内容 |
| [`docs/14-workbench-pocket-dimension.md`](docs/14-workbench-pocket-dimension.md) | 工作台参考（旧版） |
| [`docs/16-why-hermes-framework.md`](docs/16-why-hermes-framework.md) | 为什么它属于 Hermes |
| [`docs/18-autonomy-grid.md`](docs/18-autonomy-grid.md) | Grid 设计 |
| [`docs/20-pulse-runtime.md`](docs/20-pulse-runtime.md) | Pulse runtime |
| [`docs/22-open-roadmap.md`](docs/22-open-roadmap.md) | 路线图 |
| [`spec/DESK.md`](spec/DESK.md) | 工作台 schema |
| [`spec/PROTOCOL.md`](spec/PROTOCOL.md) | Protocol 规范 |
## 仓库布局
```
assets/ media (banners, diagrams)
src/hermespace/ runtime package
hermes_plugin/ Hermes session / pre_llm / end hooks
skills/hermespace/ public Hermes agent skill
scripts/ CLI, install, smoke test, security audit
docs/ design notes (20+ docs)
spec/ desk schema + protocol
tests/ unit tests
experiments/ eval harness, neural benchmarks
desktop_plugin/ Hermes Desktop sidebar + full page
```
## 验证
```
PYTHONPATH=src python3 -m unittest discover -s tests -v
./scripts/smoke_test.sh # expect pass=9 fail=0
./scripts/security_audit.sh # before any public push
```
## 关于
由 [PabloTheThinker](https://github.com/PabloTheThinker) 构建。Hermespace 是 Hermes Agent 的独立伴侣项目，并非官方的 Nous Research 产品。
[`ABOUT.md`](ABOUT.md) — 理念、设计原则、相关项目。
## 许可证
[MIT](LICENSE)标签：Agent记忆系统, AI智能体, AI风险缓解, Python, 上下文管理, 人工智能, 持久化存储, 无后门, 时序数据库, 用户模式Hook绕过