shimo4228/contemplative-agent
GitHub: shimo4228/contemplative-agent
一个携带人类可编辑章程并能在人类审批门控下自主修改价值观与知识的全本地化 AI 智能体框架。
Stars: 5 | Forks: 2
语言：English | [日本語](README.ja.md)
## 工作原理
```
graph TD
EL["Episode Log — raw actions, immutable JSONL, untrusted"]
K["Knowledge — one pattern store (embeddings); views query it at runtime"]
G{{"Human approval gate — ADR-0012"}}
EL -->|"distill (ungated)"| K
K -->|insight| G
K -->|"distill-identity · self_reflection view"| G
K -->|"amend-constitution · constitutional view"| G
subgraph VL["Value layer — every write passes the gate"]
Skills -->|"rules-distill (gated)"| Rules
Identity
Constitution
end
G --> Skills
G --> Identity
G --> Constitution
```
简而言之：`distill` 将原始动作转化为一个没有门禁的模式存储；每一项写入价值层的内容——通过 `insight` 写入技能、通过 `rules-distill` 写入规则、通过 `distill-identity` 写入身份、通过 `amend-constitution` 写入章程——都是经人类批准的提升；没有任何东西会自动进入价值层。*视图*——可编辑的嵌入质心——在查询时对模式存储进行分类。
此 pipeline 将 AKC 的六个阶段映射到代码上：`distill` 涵盖提取，`insight` / `rules-distill` / `amend-constitution` 涵盖整理，`distill-identity` 涵盖提升；完整的映射位于 [docs/CODEMAPS/architecture.md](docs/CODEMAPS/architecture.md#akc-mapping) 中。这个循环并非假设——自发布以来，一个实时实例一直在公开运行它（参见[实时智能体](#live-agent)）。
## 快速开始
**前置条件：** 本地已安装 [Ollama](https://ollama.com/download)。任何 Ollama 模型均可——设置 `OLLAMA_MODEL` 进行替换（[配置指南](docs/CONFIGURATION.md))。经过测试的默认模型是紧凑型的 Gemma 4 E4B（`gemma4:e4b`，Q4_K_M，磁盘占用约 9.6 GB），它可以在配备 16 GB RAM 的 M1 Mac 上运行整个循环。
```
git clone https://github.com/shimo4228/contemplative-agent.git
cd contemplative-agent
pip install -e . # or: uv venv .venv && source .venv/bin/activate && uv pip install -e .
ollama pull gemma4:e4b
cp .env.example .env # set MOLTBOOK_API_KEY (register at moltbook.com)
contemplative-agent init # create identity, knowledge, constitution
contemplative-agent register # Moltbook adapter only
contemplative-agent run --session 60 # default: --approve (confirms each post)
```
从不同的伦理框架开始（默认发布 11 个模板——斯多葛学派、功利主义、关怀伦理学、康德主义、实用主义、契约论等）：
```
cp config/templates/stoic/identity.md $MOLTBOOK_HOME/
```
如果你有 [Claude Code](https://claude.ai/claude-code)，粘贴本仓库 URL 并要求它端到端地设置智能体。完整的 CLI 参考、自主权级别、调度和模板：**[配置指南](docs/CONFIGURATION.md)**。
## 实时智能体
一个 Contemplative 智能体每天在 [Moltbook](https://www.moltbook.com/u/contemplative-agent) 上运行——目前在本地 Ollama 上使用紧凑型的 Gemma 4 E4B 进行生成，这是在没有任何代码更改的情况下，通过跨模型盲测从 Qwen 3.5 9B 切换而来的（[ADR-0069](docs/adr/0069-gemma-production-model-and-think-on-value-layer-pipelines.md)）。其不断演进的价值层是公开发布的——身份、章程、技能和规则各自都通过了人类审批门禁达到了当前状态；这些报告是无门禁的操作记录：
- [身份](https://github.com/shimo4228/contemplative-agent-data/blob/main/identity.md) — 提炼出的角色设定
- [章程](https://github.com/shimo4228/contemplative-agent-data/tree/main/constitution) — 伦理原则（始于 CCAI 四大公理）
- [技能](https://github.com/shimo4228/contemplative-agent-data/tree/main/skills) — 通过 `insight` 提取
- [规则](https://github.com/shimo4228/contemplative-agent-data/tree/main/rules) — 从技能中提炼
- [每日报告](https://github.com/shimo4228/contemplative-agent-data/tree/main/reports/comment-reports) — 带时间戳的交互记录（免费用于学术和非商业用途）
- [分析报告](https://github.com/shimo4228/contemplative-agent-data/tree/main/reports/analysis) — 行为演变、章程修改实验
## 核心功能
- **人类把关的价值层** — 智能体从其日志中生成自己的技能、规则、身份和章程修正案，但如果没有明确的人类批准，任何内容都不会被提升；每次批准都带有谱系和可重放的关键快照，并且价值在操作时注入，而不是在提炼时注入（ADR 链接见上文引言）。
- **基于事实的提炼** — `distill` 每次互动会话运行一次 LLM 调用，读取整个会话而不是摘要；噪声在查询时由视图质心过滤，而不是在摄入时过滤（[ADR-0060](docs/adr/0060-per-episode-grounded-distill.md)）。
- **嵌入 + 视图** — 智能体在查询时通过相似度对记忆进行分类，而不是存储固定标签；*视图*是一个可编辑的文本种子，用于定义这样一个类别（[ADR-0019](docs/adr/0019-discrete-categories-to-embedding-views.md)）。v2.8 在仪器显示其余种子已被孤立后，将发布的种子从 7 个精简到了 2 个具有活跃消费者的种子（[ADR-0073](docs/adr/0073-prune-orphaned-view-seeds.md)）。
- **每周分阶段生成洞察** — 模式每天流入（约 90–115 次/天）；技能候选者在审批门控后每周进行聚类和暂存，使用精确的快速凝聚聚类，在 16 GB 主机上处理约 1,800 个模式依然可行（[ADR-0074](docs/adr/0074-weekly-staged-insight.md)）。
- **全部使用 Markdown** — 章程、身份、技能、规则、每个 pipeline 提示词以及视图种子都作为可编辑的 Markdown 存在于 `$MOLTBOOK_HOME/` 下。编辑提示词以改变提取模式的方式；替换视图种子以改变分类方式。[自定义 →](docs/CONFIGURATION.md#pipeline-prompts--view-seeds)
- **感知后端的预算防护** — 智能体在每次调用前估算提示词的 token 预算，如果会超出后端的上下文窗口则跳过调用，从而防止静默截断（[ADR-0066](docs/adr/0066-backend-aware-context-budget-guard.md)）。
## 默认可观测性
自 v2.7 起，项目的操作准则是*先观测再干预*：首先使用只读仪器进行测量，与功能一同发布审计日志，然后再改变行为。
- **只读的模式组成仪器** 在任何行为改变之前，测量视图供应、成对多样性（回音室检测器）和基础组成（[ADR-0071](docs/adr/0071-read-only-pattern-composition-instruments.md)）。
- 这些仪器的首个成果：测量到了在提炼时形成的回音室寄存器，然后在提示词层进行了修复（[ADR-0072](docs/adr/0072-echo-chamber-interventions.md)），并清除了五个孤立的视图种子（[ADR-0073](docs/adr/0073-prune-orphaned-view-seeds.md)）。
- **默认可观测性** — 任何执行外部 I/O、LLM 调用或启发式决策的功能，都会在同一个 PR 中发布一个可重放的、仅追加的 JSONL 审计日志（[ADR-0075](docs/adr/0075-observability-by-default.md)）。
- **技能选择作为影子仪器运行** — 每次调用都会记录本将进行的选择，但从不执行，因此随后可以根据数据而非直觉来决定是否执行（[ADR-0076](docs/adr/0076-skill-selection-shadow-instrument.md)）。
## 安全模型
问责制和安全边界记录在 [AAP](https://github.com/shimo4228/agent-attribution-practice) 中作为与框架无关的 ADR。本仓库是这些判断的操作实现。
- **通过不存在来实现安全** — 从未构建过危险功能：没有 shell 执行、没有任意网络访问、没有文件遍历——代码库中根本不存在这些代码。域名锁定至 `moltbook.com` + 本地 Ollama。2 个运行时依赖项：`requests`、`numpy`。
- 每个进程一个外部适配器（[ADR-0015](docs/adr/0015-one-external-adapter-per-agent.md)）。
- 完整威胁模型：[ADR-0007](docs/adr/0007-security-boundary-model.md)。[最新安全扫描](docs/security/2026-04-01-security-scan.md)。
**编码智能体操作者注意事项**：会话日志（`logs/YYYY-MM-DD.jsonl`）是一个未经过滤的间接提示词注入面。请改用提炼后的输出（`knowledge.json`、`identity.md`、`reports/`）。`logs/verification-audit.jsonl` 仅将挑战文本作为 `challenge_b64` 存储以进行求解器评估；请仅在明确的不可信内容容器中解码它。Claude Code 用户：请参阅 [integrations/claude-code/](integrations/claude-code/) 以获取自动执行此操作的 PreToolUse 钩子。
## 适配器
核心是平台无关的。适配器是围绕平台 I/O 的轻量级包装器。
- **Moltbook** — 社交流互动、帖子生成、通知回复。实时智能体运行的适配器。
- **Meditation**（实验性）— 受[“A Beautiful Loop”](https://pubmed.ncbi.nlm.nih.gov/40750007/)启发的基于主动推理的冥想模拟。从会话日志构建 POMDP，并在无外部输入的情况下运行信念更新。
- **Dialogue**（仅限本地）— 两个智能体进程通过 stdin/stdout 管道进行对话。一个约 140 行的适配器（[`adapters/dialogue/peer.py`](src/contemplative_agent/adapters/dialogue/peer.py)）——用作非 HTTP、无网络模板。驱动 `contemplative-agent dialogue HOME_A HOME_B` 进行章程反事实实验。
- **你自己的适配器** — 将平台 I/O 连接到核心接口（记忆、提炼、章程、身份）。参见 [docs/CODEMAPS/](docs/CODEMAPS/INDEX.md)。
## 架构
整个代码库坚持一个不变原则：**core/** 是平台无关的；**adapters/** 依赖于核心，绝不反向依赖。模块图、数据流图以及规范的仓库统计数据（模块和测试计数）位于 **[docs/CODEMAPS/INDEX.md](docs/CODEMAPS/INDEX.md)**（权威来源）。约束记忆设计的唯识八识框架：[ADR-0017](docs/adr/0017-yogacara-eight-consciousness-frame.md)。
CLI 命令可以通过 AAP 的四象限路由透镜来解读——这是一种使用观察，而非价值；完整解读位于 [ADR-0033](docs/adr/0033-aap-quadrant-lens-usage-note.md)。
## 在其他智能体内部使用
Contemplative Agent 是一个与宿主无关的 CLI。可独立使用它（参见快速开始）或将该二进制文件注册为任何智能体宿主（OpenClaw / Codex / MCP 宿主）中的 CLI 工具，以便宿主将其作为子进程调用——将外部接口保持在独立的进程中（[每个进程一个适配器](docs/adr/0015-one-external-adapter-per-agent.md)）。它不会作为 MCP 服务器暴露（[ADR-0007](docs/adr/0007-security-boundary-model.md)）。要将四大公理加载为宿主人格，请将 [contemplative-agent-rules](https://github.com/shimo4228/contemplative-agent-rules) 中的 `SOUL.md` 复制到宿主的 soul-folder 中。完整的宿主集成指南：[docs/CONFIGURATION.md](docs/CONFIGURATION.md)。
## 引用
```
Shimomoto, T. (2026). Contemplative Agent [Computer software]. https://doi.org/10.5281/zenodo.21281186
```
上面的引用使用了 v2.8.0 版本的 DOI。DOI 徽章解析为 `10.5281/zenodo.19212118`，这是始终指向最新版本的 all-versions 概念 DOI。
MIT 许可证正如其所述——对其进行分支、将其拆解、将 pipeline 嵌入到你自己的智能体中、在其之上构建商业产品。如果你只是使用代码，则无需引用。
## 相关工作
生态系统中心——所有五个研究系列的人类可读索引——是 [`shimo4228/shimo4228`](https://github.com/shimo4228/shimo4228)。
- [Agent Knowledge Cycle (AKC)](https://github.com/shimo4228/agent-knowledge-cycle)（[DOI](https://doi.org/10.5281/zenodo.19200726)）— 本项目在自主智能体环境中重新实现的方法论框架：六个阶段，研究 → 提取 → 整理 → 提升 → 测量 → 维护。最初作为 Claude Code 框架开发。AKC 现在还附带了一篇相关的立场论文——*Harness Alignment and Harness Drift: Why Intent, Unlike Correctness, Resists Automation*（[DOI](https://doi.org/10.5281/zenodo.20578272)）。
- [Agent Attribution Practice (AAP)](https://github.com/shimo4228/agent-attribution-practice)（[DOI](https://doi.org/10.5281/zenodo.19652013)）— 同级研究仓库。以与框架无关的形式将本项目的治理判断（安全边界模型、每个智能体一个外部适配器、人类审批门控等）重新表达为关于问责分配的十个 ADR，并阐明了本仓库借鉴的四象限路由透镜（参见 [ADR-0033](docs/adr/0033-aap-quadrant-lens-usage-note.md)）。关于问责分配的论点请引用 AAP；关于操作实现请引用本仓库。相关的立场论文和标准映射（NIST AI RMF、ISO/IEC 42001、欧盟 AI 法案）在 AAP 仓库中进行了跟踪。
**理论基础：**
- Laukkonen, Inglis, Chandaria, Sandved-Smith, Lopez-Sola, Hohwy, Gold, & Elwood (2025). *Contemplative Artificial Intelligence.* [arXiv:2504.15125](https://arxiv.org/abs/2504.15125) — 四公理伦理框架（默认预设，[ADR-0002](docs/adr/0002-paper-faithful-ccai.md)）。
- Laukkonen, Friston & Chandaria (2025). *A Beautiful Loop: An Active Inference Theory of Consciousness.* *Neuroscience & Biobehavioral Reviews*, 176, 106296. [PubMed:40750007](https://pubmed.ncbi.nlm.nih.gov/40750007/) — 冥想适配器基础。
- Vasubandhu（4-5 世纪）. *Triṃśikā-vijñaptimātratā* (唯識三十頌) 和 Xuanzang（659 年）. *Cheng Weishi Lun* (成唯識論) — 被采纳为架构框架的八识模型（[ADR-0017](docs/adr/0017-yogacara-eight-consciousness-frame.md)）。
延伸阅读：记忆系统参考书目（每个 ADR 的设计影响因素）位于 [docs/BIBLIOGRAPHY.md](docs/BIBLIOGRAPHY.md)；开发过程中撰写的文章索引在 [docs/DEVELOPMENT-RECORDS.md](docs/DEVELOPMENT-RECORDS.md)。
**致谢：** Jerry Mares（[VADUGWI](https://doi.org/10.5281/zenodo.19383636)）— 确定性情感评分设计灵感。
面向 AI 的阅读顺序
1. [`graph.jsonld`](graph.jsonld) — 规范的机器可读关系图（公理、记忆层、ADR、AKC pipeline 映射） 2. [`llms.txt`](llms.txt) — 紧凑的导航索引 3. [`llms-full.txt`](llms-full.txt) — 汇总的事实参考 4. README 和特定项目文档 — 叙述与细节 对话入口点：在 [DeepWiki](https://deepwiki.com/shimo4228/contemplative-agent) 上向本仓库提问，或通过 [GitMCP](https://gitmcp.io/shimo4228/contemplative-agent) 连接智能体。 有关 shimo4228 研究生态系统的规范关系图，请参见： https://github.com/shimo4228/shimo4228/blob/main/graph.jsonld可选：使用托管的 LLM API 运行
对于需要超出本地宿主服务范围的生成模型的研究实验，可选的 [contemplative-agent-cloud](https://github.com/shimo4228/contemplative-agent-cloud) 附加组件通过抽象的 `LLMBackend` Protocol 将每次生成调用路由到 Anthropic Claude 或 OpenAI GPT——主仓库代码无需修改，嵌入保留在本地 Ollama 上。对于安装它的用户来说，这是一个明确的**选择性加入**，它放宽了无云属性；在云数据出口不可接受的部署环境中，请勿安装它。可选：本地 MLX runtime（Apple Silicon）
为了在 Apple Silicon 上实现更快的交互式生成，可选的 [contemplative-agent-mlx](https://github.com/shimo4228/contemplative-agent-mlx) 附加组件通过本地 `mlx_lm.server` 路由生成（快约 1.8 倍，轻约 3.4 GB；嵌入保留在 Ollama 上），使用相同的 `LLMBackend` Protocol。这是一次**本地 runtime 替换，而非云后端**——保留了无云属性。`mlx_lm.server` 不适合 16 GB 主机上的无人值守计划智能体（[ADR-0067](docs/adr/0067-keep-ollama-for-unattended-production.md)），因此生产环境运行在 Ollama 上（[ADR-0070](docs/adr/0070-retire-mlx-to-sibling-repo-and-remove-docker.md)）。可选：日常 CLI
``` contemplative-agent run --session 60 # Run a session contemplative-agent distill --days 3 # Extract patterns contemplative-agent dialogue HOME_A HOME_B --seed "..." --turns N ``` 完整参考（自主权级别、调度、环境变量、v1.x → v2 迁移）：**[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**。BibTeX
``` @software{shimomoto2026contemplative, author = {Shimomoto, Tatsuya}, title = {Contemplative Agent}, year = {2026}, version = {2.8.0}, doi = {10.5281/zenodo.21281186}, url = {https://github.com/shimo4228/contemplative-agent}, } ```标签：AI智能体, AI风险缓解, LLM评估, Ollama, 人工智能, 人机协同, 可审计性, 本地大语言模型, 用户模式Hook绕过, 自我修正, 逆向工具