eve-agent-memory

What this skill does

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

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

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

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

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

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

### Long-Term (across projects, persistent)

**Org Document Store** — versioned documents scoped to the organization.

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

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

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

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

### Shared (coordination across agent