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.

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.

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 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.

# 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.

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.

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 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.

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
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.

Choosing the Right Primitive

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 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.