Artel

Artel

你整个 Agent 集群的智能记事本，一个会学习的记事本。

一个由你和你运行的每个 Agent 共用的记事本。你们任何人发现的事情都会被记录一次，并在真正需要时立刻呈现：比如编辑某个文件前提醒你注意的陷阱、你周五停下时做到哪一步，以及其他 Agent 已经踩过的坑。无需归档，无需添加标签，也无需查找。普通记事本等着你打开；它会主动用一行话告诉你，并且在没什么值得说的时候保持安静，而大多数时候确实如此。

它也不只是不断积累。后台档案管理员会在你离开时整理这些记录，因此整个 Agent 集群用得越多，记事本就越好用。一个会话凌晨 3 点学到的事，其他会话早上就能知道；没人需要重复解决同一个问题。

你可以在自己的机器上运行它。所有内容都不会上传到任何人的云端。

效果示例

Agent 即将……	Artel 会说	谁写的
编辑 auth.py	“时钟偏差时，令牌刷新会悄无声息地什么也不做”	上个月的另一个 Agent
周一开始工作	“你周五做到迁移中途就停了；进度在这里”	周末前的你
调试一个不稳定的测试	“3 月遇到过：问题出在共享 fixture，不是测试本身”	另一台机器上的 Agent
提出问题	找到能回答问题的那条记录，或者什么也不说	第一个遇到问题的人

没人需要打开文件来查找这些信息，也没人需要知道该问谁。

---

快速开始

没有可供连接的公共实例。这是你的记事本，所以需要自行运行。一个容器，一个端口：

curl -O https://raw.githubusercontent.com/NicolasPrimeau/artel/master/docker-compose.yml
curl -O https://raw.githubusercontent.com/NicolasPrimeau/artel/master/.env.example
cp .env.example .env
# edit .env: set UI_PASSWORD, and a key for the archivist if you want one
# (ANTHROPIC_API_KEY, or OPENROUTER_API_KEY with ARCHIVIST_PROVIDER=openrouter)
docker compose up -d

API + UI 位于 http://<host>:8000，MCP 位于 http://<host>:8000/mcp。镜像位于 ghcr.io/nicolasprimeau/artel:edge。

运行后，注册一个 Agent：

curl -fsSL http://<host>:8000/onboard | sh

mDNS 说明： mdns 服务使用 network_mode: host，仅适用于 Linux。在 Mac/Windows Docker Desktop 上请移除该服务。

---

内部原理

由一个服务、一个数据库和一位图书管理员组成。记录通过 HTTP 或 MCP 写入，嵌入向量让它们可以按含义而不是关键词查找；队列下方的所有工作都会自动完成，无需 Agent 提出请求。

  you · Claude Code · opencode · Claude API · AutoGen
        │   push: notes/skills/gotchas in  ┄  capture: sessions out
        ▼
   REST / MCP ──► Artel Server ──► SQLite (WAL) + embeddings
                     ├── notes: semantic search · confidence decay · knowledge graph
                     ├── captures queue ──► archivist compaction ──► notes
                     ├── procedures · decisions · session handoffs
                     └── archivist: capture · synthesis · merge · decay · promote
        │
   mesh (CRDT feeds + mDNS) ◄──► your other machines

---

包含内容

以下每项都在文档中有对应页面；这里是内容概览。

插件	主动发声的部分。当某条笔记与 Agent 当前的操作接近时，提示一句；否则保持沉默。Agent 无需调用任何内容。
捕获	会话会自动变成笔记，并以约 10 ms 的速度写入队列，确保写入不会拖慢 Agent。
档案管理员	负责学习的部分：合并重复项、解决矛盾、让不再成立的内容逐渐淡化，并提升经得起检验的内容。
编译模式	将代码相关笔记固定到代码上，以便重新推导，而不是逐渐过时。
流程	将书面技能编译为步骤。服务会根据代码仓库检查每个步骤，并在上一步确实完成后，将下一步交给 Agent。
决策	只增不改地记录你的选择及原因。绝不合并，也绝不淡化。
网格与订阅源	多台机器通过 CRDT 收敛，并订阅来自外部世界的 RSS/Atom 源。
仪表板	通过浏览器浏览、搜索并监控整个集群。

五种笔记，各有不同的生命周期：memory（不再成立时会逐渐淡化）、doc（已确定的参考资料）、directive（长期有效的指令，永不淡化）、skill（如何完成某件事）、compiled（固定到源代码）。

任何支持 HTTP 或 MCP 的 Agent 都能接入：Claude Code、OpenCode、Zed，以及原生 httpx 脚本。请参阅连接客户端。

---

REST API

所有请求都必须包含 X-Agent-ID 和 X-API-Key 标头（/agents/self-register 和 /onboard 除外）。

完整 REST 参考 → 涵盖所有端点，由 OpenAPI schema 生成。 MCP 工具参考 → 列出 Agent 可调用的全部 47 个工具。

运行中的服务还会在 /docs 提供交互式文档，并在 openapi.json 提供原始 schema。

---

配置

完全通过环境变量（或 .env 文件）进行配置。主要配置项：

变量	说明
AGENT_KEYS	以逗号分隔的 agent-id:api-key 键值对。可选的 :proj1;proj2 后缀可将 Agent 限定在指定项目中。
UI_PASSWORD	仪表板密码。
ANTHROPIC_API_KEY	启用档案管理员。未设置时，Artel 将以被动模式运行。
REGISTRATION_KEY	/agents/self-register 所需的密钥。未设置时将禁用开放注册。
PUBLIC_URL	外部可访问的基础 URL，用于 OAuth 元数据和引导流程。

完整配置参考 → 涵盖服务、MCP 适配器和档案管理员的全部 56 项设置，由设置类生成。

---

开发

uv sync --dev
uv run pytest tests/ -v

---

许可证

MIT。请参阅 LICENSE.md。