eve-agent-memory

Eve Agent Memory

Eve Horizon 上的 Agent 没有内置的“记忆”原语，但平台提供了涵盖各种时间尺度的存储系统。本技能将介绍如何将它们组合起来，为能够学习、记忆和分享的 Agent 构建连贯的记忆。

记忆问题

每个 Agent 开始时都是全新的。如果没有经过深思熟虑的记忆设计，Agent 会：

• 在每项任务中重复发现相同的事实。
• 在任务结束时丢失上下文。
• 无法与同级 Agent 分享学到的知识。
• 累积没有过期时间的陈旧信息。

要解决这个问题，请将要记住的内容映射到存储位置，并针对不同的时间尺度使用合适的原语。

按时间尺度划分的存储原语

短期（单项任务内）

工作区文件——任务执行期间可用的 git 仓库检出内容。

# Workspace is at $EVE_REPO_PATH
# Write working state to .eve/ (gitignored by convention)
echo '{"findings": [...]}' > .eve/agent-scratch.json

# Workspace modes control sharing:
#   job       — fresh checkout per job (default)
#   session   — shared across jobs in a session
#   isolated  — no git state, pure scratch
eve job create --workspace-mode session --workspace-key "auth-sprint"

用途：临时笔记、中间结果、协作收件箱文件。其设计本身就是临时的——除非提交到 git 或保存到其他位置，否则工作区状态不会在任务结束后保留。

协作收件箱——.eve/coordination-inbox.md 会在任务开始时根据协作线程中的消息自动生成。读取它即可了解同级 Agent 的状态，无需调用 API。

Agent KV Store——支持设置可选 TTL 的轻量级运行状态。用途：功能标记、计数器、Agent 状态机、去重键。按命名空间分区。

# Set a KV value with TTL
eve kv set --org $ORG_ID --agent $AGENT_SLUG --key "pr-123-status" --value '{"phase":"review"}' --namespace workflow --ttl 86400

# Get a KV value
eve kv get --org $ORG_ID --agent $AGENT_SLUG --key "pr-123-status" --namespace workflow

# List keys in a namespace
eve kv list --org $ORG_ID --agent $AGENT_SLUG --namespace workflow

# Batch get multiple keys
eve kv mget --org $ORG_ID --agent $AGENT_SLUG --keys "pr-123-status,pr-456-status" --namespace workflow

# Delete a key
eve kv delete --org $ORG_ID --agent $AGENT_SLUG --key "pr-123-status" --namespace workflow

中期（项目内的多个任务之间）

任务附件——附加到任意任务的命名键值对。任务完成后仍会保留。

# Store findings
eve job attach $EVE_JOB_ID --name findings.json --content '{"patterns": [...]}'
eve job attach $EVE_JOB_ID --name summary.md --file ./analysis-summary.md

# Retrieve from any job (including parent/child)
eve job attachment $PARENT_JOB_ID findings.json --out ./prior-findings.json
eve job attachments $JOB_ID  # list all

用途：任务输出、决策记录、分析结果。附件与特定任务关联，因此可通过任务 ID 检索。适合在父任务和子任务之间传递结构化数据。

线程——跨会话保持连续性的消息序列。

# Project threads maintain chat context
eve thread messages $THREAD_ID --since 1h

# Coordination threads connect parent/child agents
eve thread post $COORD_THREAD_ID --body '{"kind":"update","body":"Found 3 auth issues"}'
eve thread follow $COORD_THREAD_ID  # poll for sibling updates

用途：Agent 间通信、持续上下文、协作。线程摘要可提供压缩后的历史记录。团队分派任务时会自动创建协作线程（coord:job:{parent_job_id}）。

线程提炼——将线程对话转换为记忆文档或组织文档。用途：将有价值的讨论成果保存为可搜索的知识。

eve thread distill $THREAD_ID --org $ORG_ID --agent reviewer --category learnings --key "auth-discussion-findings"

资源引用——指向组织文档的带版本指针，会挂载到任务工作区中。

eve job create \
  --description "Review the approved plan" \
  --resource-refs='[{"uri":"org_docs:/pm/features/FEAT-123.md@v3","label":"Plan","mount_path":"pm/plan.md"}]'

用途：将特定版本的文档固定为任务输入。引用的文档会在指定的挂载路径中加载到工作区。事件会跟踪加载成功或失败的情况。

长期（跨项目、持久）

组织文档存储 — 组织范围内的版本化文档。

# Store knowledge
eve docs write --org $ORG_ID --path /agents/learnings/auth-patterns.md --file ./auth-patterns.md

# Retrieve
eve docs read --org $ORG_ID --path /agents/learnings/auth-patterns.md
eve docs list --org $ORG_ID --prefix /agents/learnings/

# Search
eve docs search --org $ORG_ID --query "authentication retry"

适用于：精选知识、决策记录、习得的模式。支持版本控制（每次更新都会创建一个新版本）。会在事件主干上发出 system.doc.created/updated/deleted 事件。最适合经过审阅、完善并共享的知识。

Agent 记忆命名空间 — 按 Agent 范围的路径约定，以组织文档的形式存储精选知识。类别：learnings、decisions、runbooks、context、conventions。支持置信度分数、标签、审阅日期和过期时间。适用于：积累的专业知识、决策记录、操作手册。

# Store a memory entry
eve memory set --org $ORG_ID --agent reviewer --category learnings --key "auth-retry-patterns" \
  --content "Always use exponential backoff..." --confidence 0.9 --tags "auth,reliability" --review-in 30d

# Get a memory entry
eve memory get --org $ORG_ID --agent reviewer --key "auth-retry-patterns" --category learnings

# List entries
eve memory list --org $ORG_ID --agent reviewer --category learnings --limit 20

# Delete an entry
eve memory delete --org $ORG_ID --agent reviewer --category learnings --key "auth-retry-patterns"

# Search across memory (all agents or specific)
eve memory search --org $ORG_ID --query "auth retry patterns" --agent reviewer --limit 10

命名空间约定：/agents/{slug}/memory/{category}/{key}.md 或 /agents/shared/memory/...

组织文件系统 — 每个组织共享的文件存储，会挂载到 Agent 工作区中的 .org/，并同步到本地计算机。

# Agents access .org/ directly in their workspace (all execution paths)
ls .org/                                    # browse org files
cat .org/shared/runbook.md                  # read shared knowledge
echo "new finding" >> .org/agents/reviewer/notes.md  # write agent-scoped files

# Developers sync to local machines
eve fs sync init --org $ORG_ID --local ~/Eve/acme --mode two-way
eve fs sync status --org $ORG_ID
eve fs sync logs --org $ORG_ID --follow

适用于：大型知识库、设计素材、文档目录树。无论执行路径是 agent-runtime 还是 worker，Agent 都能在工作区中看到 .org/。默认以 Markdown 为主。由事件驱动的通知（file.created/updated/deleted）。最适合以文件树形式存在，且适合 Agent 和人类共同编辑的知识。

技能和技能包 — 封装为可复用形式的提炼模式。

适用于：将反复出现的工作流和来之不易的知识编写为可复用的指令。当 Agent 发现值得保留的模式时，将其提炼为一项技能（参见 eve-skill-distillation）。技能是保真度最高的长期记忆形式——它们不仅存储信息，还会教会你如何使用这些信息。

托管数据库 — 环境范围内的 Postgres 实例，Agent 可通过 SQL 访问。

eve db sql --env $ENV --sql "SELECT key, value FROM agent_memory WHERE agent_id = 'reviewer' AND expires_at > NOW()"
eve db sql --env $ENV --sql "INSERT INTO agent_memory (agent_id, key, value) VALUES ('reviewer', 'last_review', '...')" --write

适用于：结构化查询、关系数据，以及任何适合使用 SQL 的场景。需要通过迁移设置架构。使用 eve db rls init --with-groups 创建访问受控的 Agent 记忆表。

共享（Agent 之间的协作）

组织线程 — 组织范围内的消息序列，用于跨项目协作。

eve thread list --org $ORG_ID
eve thread post $ORG_THREAD_ID --body '{"kind":"directive","body":"All agents: use new auth pattern"}'

事件主干 — 用于响应式工作流的发布/订阅事件总线。

eve event emit --type=agent.memory.updated --source=app --payload '{"agent":"reviewer","key":"patterns"}'
eve event list --type agent.memory.*

适用于：广播知识更新，以及在记忆发生变化时触发响应式工作流。

统一搜索 — 通过一次查询搜索记忆、文档、线程、附件和事件。适用于：开始工作前查找相关的已有知识。

eve search --org $ORG_ID --query "auth retry patterns" --sources memory,docs,threads --limit 10 --agent reviewer

记忆模式

模式 1：任务范围内的临时存储

最简单的模式。在执行期间将工作状态写入工作区文件。任务结束后不会保留任何内容。

Job starts → read inputs → write .eve/scratch.json → process → complete

适用场景：不需要记忆的单任务。

模式 2：父子知识传递

通过附件和线程，在编排器与工作进程之间传递知识。

Parent creates children with resource-refs →
Children execute, attach findings →
Parent resumes, reads child attachments →
Parent synthesizes into final output

# Child stores its findings
eve job attach $EVE_JOB_ID --name findings.json --content "$FINDINGS"

# Parent reads child findings on resume
for child_id in $CHILD_IDS; do
  eve job attachment $child_id findings.json --out ./child-${child_id}.json
done

适用场景：经过编排的工作，其中子任务发现的信息是父任务所需的。

模式 3：组织知识库

构建可持久保存、可搜索的知识，使其跨项目和时间保留。

Agent discovers pattern →
Check if existing doc covers it (eve docs search) →
  If yes: update with new information (eve docs write)
  If no: create new document (eve docs write) →
Emit event for other agents (eve event emit)

由 Agent 维护的文档命名空间约定：

/agents/{agent-slug}/learnings/     — patterns and discoveries
/agents/{agent-slug}/decisions/     — decision records with rationale
/agents/{agent-slug}/runbooks/      — operational procedures
/agents/shared/                     — cross-agent shared knowledge

适用场景：随时间不断积累，且应供组织中的任何 Agent 使用的知识。

模式 4：记忆增强型任务启动

组合使用基础组件，在每项任务开始时为 Agent 提供相关上下文。

Job starts →
Read coordination inbox (.eve/coordination-inbox.md) →
Query org docs for relevant prior knowledge (eve docs search) →
Check parent/sibling attachments for recent findings →
Proceed with enriched context

# Startup sequence
cat .eve/coordination-inbox.md 2>/dev/null  # sibling context
ls .org/ 2>/dev/null                         # org filesystem (shared files)
eve docs search --org $ORG_ID --query "$JOB_DESCRIPTION_KEYWORDS"  # prior knowledge
eve job attachments $PARENT_JOB_ID  # parent context

适用场景：任何能从记住此前发生的事情中获益的 Agent。

模式 5：先搜索，再写入

创建新文档前先搜索已有知识。

eve search --org $ORG_ID --query "auth retry patterns" --sources memory,docs →
  If relevant result exists: read and update it
  If no result: create new memory doc

适用场景：任何会创建知识文档的 Agent。可避免重复。

模式 6：KV 状态机

使用 KV 存储跟踪多步骤 Agent 工作流。

eve kv set --org $ORG_ID --agent reviewer --namespace workflow --key "pr-123" --value '{"phase":"review","started":"..."}' --ttl 86400

适用场景：跟踪多阶段任务中的逐步进度，状态需要在短暂中断后保留，但无需永久保存。

模式 7：从线程到知识的流程

将有价值的线程对话提炼为可搜索的记忆。

eve thread distill $THREAD_ID --org $ORG_ID --agent reviewer --category learnings --key "auth-discussion-findings"

适用场景：线程产生了值得在对话结束后继续保留的知识。

选择合适的基础组件

问题	答案 → 基础组件
只需要在当前任务期间使用？	Workspace files
需要带 TTL 的轻量状态？	Agent KV Store
需要向父级／子级传递数据？	Job attachments
需要滚动保留对话上下文？	Threads
需要将对话提炼为知识？	Thread distillation → Agent Memory
需要经过整理和分类的 Agent 知识？	Agent Memory Namespaces
需要有版本控制且可搜索的文档？	Org Document Store
需要在组织内的多个 Agent 之间共享文件？	Org Filesystem（.org/ 挂载）
需要与本地编辑同步的文件树？	Org Filesystem（CLI sync）
需要应用范围内的二进制／对象存储？	Object Store（manifest）
需要结构化查询（SQL）？	Managed database
需要封装可复用的工作流？	Skills
需要响应式通知？	Event spine
需要跨所有内容进行搜索？	Unified Search

访问控制

存储基础组件遵循 Eve 的访问模型：

• Secrets：按作用域解析（项目 → 用户 → 组织 → 系统）。切勿在 secrets 中存储记忆。
• Org docs：需要组织成员身份。需要精细控制时，请使用访问组。
• Database：使用带有组感知策略的 RLS，实现多 Agent 隔离。
• Threads：限定在项目或组织范围内。任务令牌可授予对协调线程的访问权限。
• Filesystem：组织级权限，可通过访问组设置可选的路径 ACL。

# Check agent's effective access
eve access can --resource orgdocs:/agents/shared/ --action read
eve access memberships --org $ORG_ID

反模式

• 将所有内容都存储在工作区文件中 — 任务结束后文件就会消失。值得保留的内容请使用附件或组织文档。
• 将冗长的线程消息当作记忆 — 线程用于交流，而非存储。发布摘要，将详细内容存入文档。
• 没有过期策略 — 没有生命周期管理的记忆会变成噪声。为文档标注日期并定期清理。
• 在多个基础组件中重复知识 — 每条知识只选一个真实来源。其他地方引用它，不要复制。
• 写入前不搜索 — 创建新文档前，务必先检查知识是否已存在。更新优于新建。

当前缺口和变通方案

目前有些记忆模式需要手动组装：

• 任务启动时不会自动沿用上下文 — 需要手动构建启动序列（见模式 4）。平台不会在启动任务时自动加载已有知识。
• 不会自动将线程提炼为知识 — 可以手动运行 eve thread distill，但目前还没有基于 cron 或触发器的自动化。
• 没有文档生命周期自动化 — 使用 --review-in 和 --expires-in 标志设置审查日期和过期时间。使用 eve docs stale 查找逾期文档。目前还无法自动清理。