Memory Engine

Beyond MEMORY.md as a static file, the active memory engine treats memory as a live store of timestamped entries with tags and optional TTL. Agents read relevant entries automatically; write new ones explicitly.

What gets stored

Free-text content
Optional tags for filtering
Optional sessionKey (per-session scope)
Optional TTL — entries auto-delete after expiry
Created + last-accessed timestamps

CLI usage

vesper memory write bags-hunter "User prefers 24h+ liquidity tokens"
vesper memory write bags-hunter "BTC ATH thesis: 200k by Q4" \
  --tag thesis --ttl-hours 720

vesper memory list bags-hunter
vesper memory list bags-hunter --tag thesis
vesper memory search bags-hunter "ATH thesis"
vesper memory delete bags-hunter m_1737...
vesper memory clear bags-hunter

API

POST   /memory/:agent          {content, tags?, sessionKey?, ttlMs?}
GET    /memory/:agent          ?tag=X&sessionKey=Y
POST   /memory/:agent/search   {query, limit?}
DELETE /memory/:agent/:id
DELETE /memory/:agent          (clear all)

Auto-inclusion in context

The Context Engine injects the top 5 most relevant entries into every system prompt. Relevance is keyword-scored against recent messages.

Storage

User-installed: ~/.openvesper/agents/<mode>/memory/<id>.json
Bundled: .agents/<mode>/memory/<id>.json

File mode 0600. Nothing transmitted off-machine.

Source

Implementation: apps/gateway/src/memory-engine.ts