Eve Agent Memory

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.

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.

Storage Primitives by Timescale

Short-Term (within a job)

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

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.

Agent KV Store — lightweight operational state with optional TTL. Use for: feature flags, rate counters, agent state machines, deduplication keys. Namespace-partitioned.

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

Medium-Term (across jobs within a project)

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

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.

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.

Thread Distillation — convert thread conversations into memory docs or org docs. Use for: preserving valuable discussion outcomes as searchable knowledge.

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

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

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.

Long-Term (across projects, persistent)

Org Document Store — versioned documents scoped to the organization.

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"

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.

Agent Memory Namespaces — curated knowledge stored as org docs with agent-scoped path conventions. Categories: learnings , decisions , runbooks , context , conventions . Supports confidence scores, tags, review dates, and expiration. Use for: accumulated expertise, decision logs, operational runbooks.

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

Namespace convention: /agents/{slug}/memory/{category}/{key}.md or /agents/shared/memory/...

Org Filesystem — shared per-org file storage mounted at .org/ in agent workspaces and synced to local machines.

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

Use for: large knowledge bases, design assets, documentation trees. Agents see .org/ in their workspace regardless of execution path (agent-runtime or worker). Markdown-first defaults. Event-driven notifications (file.created/updated/deleted ). Best for knowledge that lives as a file tree and benefits from both agent and human 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.

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.

Shared (coordination across agents)

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

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.

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.

Unified Search — single query across memory, docs, threads, attachments, events. Use for: finding relevant prior knowledge before starting work.

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

Memory Patterns

Pattern 1: Job-Scoped Scratch

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.

Pattern 2: Parent-Child Knowledge Passing

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

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.

Pattern 3: Org Knowledge Base

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 write) If no: create new document (eve docs write) → 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.

Pattern 4: Memory-Augmented Job Start

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

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

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

Pattern 5: Search-Before-Write

Search existing knowledge before creating new docs.

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

When to use: any agent that creates knowledge documents. Prevents duplication.

Pattern 6: KV State Machine

Use KV store to track multi-step agent workflows.

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

When to use: tracking step-by-step progress in multi-phase jobs where state must survive brief interruptions but not forever.

Pattern 7: Thread-to-Knowledge Pipeline

Distill valuable thread conversations into searchable memory.

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

When to use: after a thread produces knowledge worth preserving beyond the conversation.

Choosing the Right Primitive

Question Answer → Primitive

Need it only during this job? Workspace files

Need lightweight state with TTL? Agent KV Store

Need to pass data to parent/children? Job attachments

Need rolling conversation context? Threads

Need to distill a conversation into knowledge? Thread distillation → Agent Memory

Need curated, categorized agent knowledge? Agent Memory Namespaces

Need versioned, searchable documents? Org Document Store

Need shared files across agents in the org? Org Filesystem (.org/ mount)

Need file-tree sync with local editing? Org Filesystem (CLI sync)

Need app-scoped binary/object storage? Object Store (manifest)

Need structured queries (SQL)? Managed database

Need to encode a reusable workflow? Skills

Need reactive notifications? Event spine

Need to search across everything? Unified Search

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.

Check agent's effective access

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

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 automatic context carryover at job start — build startup sequences manually (see Pattern 4). The platform does not auto-hydrate prior knowledge on job launch.

• No automatic thread-to-knowledge distillation — manual eve thread distill exists, but no cron or trigger-based automation yet.

• No document lifecycle automation — set review dates and expiration via --review-in and --expires-in flags. Use eve docs stale to find overdue documents. Automated cleanup is not yet available.