eve-agent-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eve Agent Memory

Eve Agent 内存

Agents on Eve Horizon have no built-in "memory" primitive, but the platform provides storage systems at every timescale. This skill teaches how to compose them into coherent memory for agents that learn, remember, and share.

Eve Horizon平台上的Agent没有内置的「内存」原语，但平台提供了覆盖所有时间维度的存储系统。本技能将讲解如何将这些存储系统组合为连贯的内存体系，让Agent能够学习、记忆并共享知识。

The Memory Problem

内存问题

Every agent starts cold. Without deliberate memory design, agents:

Re-discover the same facts on every job.
Lose context when jobs end.
Cannot share learned knowledge with sibling agents.
Accumulate stale information with no expiry.

Solve this by mapping what to remember to where to store it, using the right primitive for each timescale.

每个Agent初始状态下都没有任何记忆。若不进行刻意的内存设计，Agent会出现以下问题：

在每次任务中重复发现相同的事实。
任务结束后丢失上下文信息。
无法与同组Agent共享已学习的知识。
积累未过期的陈旧信息。

解决这些问题的方法是，根据不同的时间维度，将「需要记忆的内容」映射到「对应的存储位置」，为每种场景选择合适的存储原语。

Storage Primitives by Timescale

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

Short-Term (within a job)

短期（单任务内）

Workspace files — the git repo checkout available during job execution.

bash

undefined

工作区文件——任务执行期间可用的Git仓库检出目录。

bash

undefined

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"


Use for: scratch notes, intermediate results, coordination inbox files. Ephemeral by design — workspace state does not survive the job unless committed to git or saved elsewhere.

**Coordination inbox** — `.eve/coordination-inbox.md` is auto-generated from coordination thread messages at job start. Read it for sibling status without API calls.

eve job create --workspace-mode session --workspace-key "auth-sprint"


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

**协作收件箱**——`.eve/coordination-inbox.md`会在任务启动时自动从协作线程消息生成。无需调用API即可查看同组Agent的状态。

Medium-Term (across jobs within a project)

中期（项目内跨任务）

Job attachments — named key-value pairs attached to any job. Survive after job completion.

bash

undefined

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

bash

undefined

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


Use for: job outputs, decision records, analysis results. Attached to a specific job, so retrievable by job ID. Good for passing structured data between parent and child jobs.

**Threads** — message sequences with continuity across sessions.

```bash

eve job attachment $PARENT_JOB_ID findings.json --out ./prior-findings.json eve job attachments $JOB_ID # list all


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

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

```bash

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


Use for: inter-agent communication, rolling context, coordination. Thread summaries provide compressed history. Coordination threads (`coord:job:{parent_job_id}`) are auto-created for team dispatches.

**Resource refs** — versioned pointers to org documents, mounted into job workspaces.

```bash
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"}]'

Use for: pinning specific document versions as job inputs. The referenced document is hydrated into the workspace at the specified mount path. Events track hydration success/failure.

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}`）会为团队调度自动创建。

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

```bash
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"}]'

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

Long-Term (across projects, persistent)

长期（跨项目、持久化）

Org Document Store — versioned documents scoped to the organization.

bash

undefined

组织文档存储——组织级别的版本化文档。

bash

undefined

Store knowledge

eve docs create --org $ORG_ID --path /agents/learnings/auth-patterns.md --file ./auth-patterns.md eve docs update --org $ORG_ID --path /agents/learnings/auth-patterns.md --file ./updated.md

Retrieve

eve docs get --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"


Use for: curated knowledge, decision logs, learned patterns. Versioned (every update creates a new version). Emits `system.doc.created/updated/deleted` events on the event spine. Best for knowledge that is reviewed, refined, and shared.

**Org Filesystem (sync)** — bidirectional file sync between local machines and org storage.

```bash

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


用途：整理后的知识、决策日志、已学习的模式。支持版本控制（每次更新都会创建新版本）。在事件总线上触发`system.doc.created/updated/deleted`事件。最适合用于经过审核、优化并共享的知识。

**组织文件系统（同步）**——本地机器与组织存储之间的双向文件同步。

```bash

Set up sync (developer/operator machine)

eve fs sync init --org $ORG_ID --local ~/Eve/acme --mode two-way

Status and monitoring

eve fs sync status --org $ORG_ID eve fs sync logs --org $ORG_ID --follow


Use for: large knowledge bases, design assets, documentation trees. Markdown-first defaults. Syncthing-based data plane with event-driven notifications (`file.created/updated/deleted`). Best for knowledge that lives as a file tree and benefits from local editing.

**Skills and Skillpacks** — distilled patterns packaged for reuse.

Use for: encoding recurring workflows and hard-won knowledge as reusable instructions. When an agent discovers a pattern worth preserving, distill it into a skill (see `eve-skill-distillation`). Skills are the highest-fidelity form of long-term memory — they don't just store information, they teach how to use it.

**Managed databases** — environment-scoped Postgres instances with agent-accessible SQL.

```bash
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

Use for: structured queries, relationship data, anything that benefits from SQL. Requires schema setup via migrations. Use

eve db rls init --with-groups

for access-controlled agent memory tables.

eve fs sync status --org $ORG_ID eve fs sync logs --org $ORG_ID --follow


用途：大型知识库、设计资产、文档树。默认优先支持Markdown。基于Syncthing的数据平面，带有事件驱动的通知（`file.created/updated/deleted`）。最适合以文件树形式存在、且需要本地编辑的知识。

**技能与技能包**——打包为可复用形式的提炼后的模式。

用途：将重复的工作流和积累的知识编码为可复用的指令。当Agent发现值得保留的模式时，可将其提炼为技能（参考`eve-skill-distillation`）。技能是最高保真度的长期内存形式——它们不仅存储信息，还教授如何使用这些信息。

**托管数据库**——环境级别的Postgres实例，Agent可通过SQL访问。

```bash
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处理的场景。需要通过迁移来设置Schema。使用

eve db rls init --with-groups

来创建支持访问控制的Agent内存表。

Shared (coordination across agents)

共享（跨Agent协作）

Org threads — org-scoped message sequences for cross-project coordination.

bash

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

Event spine — pub/sub event bus for reactive workflows.

bash

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

Use for: broadcasting knowledge updates, triggering reactive workflows when memory changes.

组织线程——组织级别的消息序列，用于跨项目协作。

bash

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

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

bash

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

用途：广播知识更新、在内存发生变化时触发响应式工作流。

Memory Patterns

内存模式

Pattern 1: Job-Scoped Scratch

模式1：任务级临时存储

The simplest pattern. Write working state to workspace files during execution. Nothing survives the job.

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

When to use: single-job tasks with no memory requirement.

最简单的模式。在执行期间将工作状态写入工作区文件。任务结束后所有内容都会消失。

任务启动 → 读取输入 → 写入.eve/scratch.json → 处理 → 完成

适用场景：无需记忆的单任务操作。

Pattern 2: Parent-Child Knowledge Passing

模式2：父子Agent知识传递

Pass knowledge between orchestrator and workers using attachments and threads.

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

bash

undefined

使用附件和线程在编排器与工作Agent之间传递知识。

父Agent通过资源引用创建子Agent →
子Agent执行任务，附加结果 →
父Agent恢复执行，读取子Agent的附件 →
父Agent将结果合成为最终输出

bash

undefined

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


When to use: orchestrated work where children discover information the parent needs.

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


适用场景：编排式工作，子Agent发现的信息需要被父Agent使用。

Pattern 3: Org Knowledge Base

模式3：组织知识库

Build persistent, searchable knowledge that survives across projects and time.

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

Namespace convention for agent-maintained docs:

/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

When to use: knowledge that accumulates over time and should be available to any agent in the org.

构建跨项目、持久化的可搜索知识库。

Agent发现模式 →
检查现有文档是否已覆盖该模式（eve docs search） →
  若是：用新信息更新文档（eve docs update）
  若否：创建新文档（eve docs create） →
向其他Agent发送事件通知（eve event emit）

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

/agents/{agent-slug}/learnings/     — 模式与发现成果
/agents/{agent-slug}/decisions/     — 带有决策依据的记录
/agents/{agent-slug}/runbooks/      — 操作流程
/agents/shared/                     — 跨Agent共享知识

适用场景：随时间积累、需要供组织内所有Agent访问的知识。

Pattern 4: Memory-Augmented Job Start

模式4：内存增强型任务启动

Combine primitives to give an agent relevant context at the start of every job.

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

bash

undefined

组合多种原语，让Agent在每次任务启动时获取相关上下文。

任务启动 →
读取协作收件箱（.eve/coordination-inbox.md） →
查询组织文档获取相关历史知识（eve docs search） →
检查父/同组Agent的附件获取最新结果 →
基于增强后的上下文继续执行

bash

undefined

Startup sequence

cat .eve/coordination-inbox.md 2>/dev/null # sibling context eve docs search --org $ORG_ID --query "$JOB_DESCRIPTION_KEYWORDS" # prior knowledge eve job attachments $PARENT_JOB_ID # parent context


When to use: any agent that benefits from remembering what happened before.

cat .eve/coordination-inbox.md 2>/dev/null # sibling context eve docs search --org $ORG_ID --query "$JOB_DESCRIPTION_KEYWORDS" # prior knowledge eve job attachments $PARENT_JOB_ID # parent context


适用场景：任何需要记住之前发生过的事情的Agent。

Choosing the Right Primitive

选择合适的原语

Question	Answer → Primitive
Need it only during this job?	Workspace files
Need to pass data to parent/children?	Job attachments
Need rolling conversation context?	Threads
Need versioned, searchable documents?	Org Document Store
Need file-tree sync with local editing?	Org Filesystem
Need structured queries (SQL)?	Managed database
Need to encode a reusable workflow?	Skills
Need reactive notifications?	Event spine

问题	答案 → 原语
仅需在本次任务中使用？	工作区文件
需要向父/子Agent传递数据？	任务附件
需要滚动对话上下文？	线程
需要版本化、可搜索的文档？	组织文档存储
需要支持本地编辑的文件树同步？	组织文件系统
需要结构化查询（SQL）？	托管数据库
需要编码可复用的工作流？	技能
需要响应式通知？	事件总线

Access Control

访问控制

Storage primitives respect Eve's access model:

Secrets: scoped resolution (project → user → org → system). Never store memory in secrets.
Org docs: org membership required. Use access groups for fine-grained control.
Database: use RLS with group-aware policies for multi-agent isolation.
Threads: project-scoped or org-scoped. Job tokens grant access to coordination threads.
Filesystem: org-level permissions, with optional path ACLs via access groups.

bash

undefined

存储原语遵循Eve的访问模型：

密钥：按作用域解析（项目→用户→组织→系统）。请勿在密钥中存储内存数据。
组织文档：需要组织成员身份。使用访问组实现细粒度控制。
数据库：使用带有组感知策略的RLS实现多Agent隔离。
线程：项目级或组织级。任务令牌会授予协作线程的访问权限。
文件系统：组织级权限，可通过访问组设置可选的路径ACL。

bash

undefined

Check agent's effective access

eve access can --resource orgdocs:/agents/shared/ --action read eve access memberships --org $ORG_ID

undefined

eve access can --resource orgdocs:/agents/shared/ --action read eve access memberships --org $ORG_ID

undefined

Anti-Patterns

反模式

Storing everything in workspace files — dies with the job. Use attachments or org docs for anything worth keeping.
Giant thread messages as memory — threads are for communication, not storage. Post summaries, store details in docs.
No expiry strategy — memory without lifecycle becomes noise. Date your documents, prune periodically.
Duplicating knowledge across primitives — pick one source of truth per piece of knowledge. Reference it from other places, don't copy it.
Skipping search before writing — always check if the knowledge already exists before creating a new document. Update beats create.

所有内容都存储在工作区文件中——任务结束后数据会丢失。任何需要保留的内容都应使用附件或组织文档存储。
用巨型线程消息作为内存——线程是用于通信的，不是存储。发布摘要，将详细内容存储在文档中。
没有过期策略——没有生命周期的内存会变成噪音。为文档添加日期标记，定期清理。
在多个原语中重复存储知识——为每条知识选择单一的事实来源。从其他位置引用它，不要复制。
写入前不搜索——创建新文档前务必检查知识是否已存在。更新优于创建。

Current Gaps and Workarounds

当前局限与替代方案

Some memory patterns require manual assembly today:

No dedicated KV store — use managed DB with a simple
```
key/value/ttl
```
table, or org docs with path-based keys.
No vector search — use keyword search via
```
eve docs search
```
for now. Structure documents with clear headings and terms to improve retrieval.
No automatic context carryover — build startup sequences manually (see Pattern 4). Consider encoding these as job templates or skill instructions.
No document lifecycle automation — set TTLs manually or build periodic cleanup jobs. Tag documents with creation dates and review dates.

目前部分内存模式需要手动组合实现：

无专用KV存储——使用托管数据库创建简单的
```
key/value/ttl
```
表，或使用基于路径键的组织文档。
无向量搜索——目前使用
```
eve docs search
```
进行关键词搜索。为文档设置清晰的标题和术语以提高检索效率。
无自动上下文传递——手动构建启动序列（参考模式4）。可将这些序列编码为任务模板或技能指令。
无文档生命周期自动化——手动设置TTL或构建定期清理任务。为文档标记创建日期和审核日期。