Tools reference

All inputs are JSON objects. Tools that read or write memories require agent_id and user_id. Most tools also accept org_id and workspace_id, which default to the server environment variables EDEN_ORG_ID and EDEN_WORKSPACE_ID.

Quick reference

Tool	Purpose	Mutates data
eden_remember	Store a durable memory	Yes
eden_recall	Semantic recall	No
eden_search	Keyword search	No
eden_search_semantic	Semantic search with metadata filters	No
eden_edit	Update a memory by ID	Yes
eden_forget	Soft-delete a memory by ID	Yes
eden_forget_expired	Delete all expired memories	Yes
eden_health	Health, sync, usage, and telemetry snapshot	No
eden_vacuum	SQLite WAL checkpoint	Yes (store maintenance)
eden_prune	Bulk soft-delete or hard-delete memories	Yes
eden_migrate	Remap org_id/workspace_id for a scope	Yes
eden_packet	Build a deterministic knowledge packet	No
eden_export_snapshot	Export an encrypted database snapshot	No
eden_import_snapshot	Import an encrypted snapshot	Yes (replaces DB)
eden_sync	One-shot bidirectional sync with a peer DB	Yes
eden_pair_device	Pair with a local peer DB using SPAKE2	Yes
eden_sync_loop	Start/stop/status/once for relay sync loop	Yes (when running)
eden_relay_server	Start/stop/status a local relay server	Yes (when starting)
eden_relay_register	Register this device with a relay	Yes (relay directory)
eden_pair_create_invitation	Create a relay-mediated PAKE invitation	Yes (relay enrolment)
eden_pair_accept_invitation	Accept a relay-mediated PAKE invitation	Yes

Tools that mutate data either require an explicit confirmation (confirm: true) or default to dry-run mode.

Memory tools

eden_remember

Store a durable memory.

{
  "agent_id": "my-client",
  "user_id": "yakov",
  "content": "User prefers Python examples and concise sentences.",
  "metadata": {"source": "direct-statement", "domain": "style"},
  "ttl_ms": null,
  "workspace_id": "eden-releases",
  "org_id": "your-org"
}

• agent_id and user_id are required.
• ttl_ms: null means the memory never expires. A positive integer sets an expiry in milliseconds.
• workspace_id scopes the memory to a project; org_id is for fleet contexts.
• Legacy aliases: observer_id → agent_id, observed_id → user_id, fact → content.

Response:

{"id": "a1b2c3d4-...", "status": "remembered"}

eden_recall

Semantic recall for this user. Call once at task start and before finalizing decisions that could contradict past preferences.

{
  "agent_id": "my-client",
  "user_id": "yakov",
  "workspace_id": "eden-releases",
  "query": "style and tone preferences",
  "limit": 5
}

Response:

{
  "results": [
    {
      "id": "a1b2c3d4-...",
      "content": "User prefers Python examples and concise sentences.",
      "metadata": {"source": "direct-statement", "domain": "style"},
      "score": 0.92
    }
  ]
}

Legacy aliases: topic / top_k → query / limit.

See Scopes and identity for how agent_id, user_id, org_id, and workspace_id filter results.

eden_search

Keyword search over stored memory content.

{
  "agent_id": "my-client",
  "user_id": "yakov",
  "query": "Python examples",
  "limit": 10
}

eden_search_semantic

Semantic search with optional metadata filters.

{
  "agent_id": "my-client",
  "user_id": "yakov",
  "query": "What style does the user prefer?",
  "filters": {"domain": "style"},
  "limit": 5
}

The first semantic call may load the bundled embedding model. Subsequent calls are fast.

eden_edit

Update an existing memory by ID. Use this when a fact changes instead of storing a duplicate.

{
  "id": "a1b2c3d4-...",
  "content": "User prefers Python examples, concise sentences, and explicit types.",
  "metadata": {"source": "user-correction", "domain": "style"},
  "ttl_ms": null
}

eden_forget

Delete a specific memory by ID.

{"id": "a1b2c3d4-..."}

eden_forget_expired

Remove all memories past their TTL. This is a housekeeping tool; do not call it automatically.

{}

Optional: agent_id, user_id, org_id, workspace_id to scope the cleanup.

eden_health

Return a combined health, sync, usage, and telemetry snapshot.

{}

The total count is global and not affected by scoping.

eden_vacuum

Compact the SQLite store. Call only when explicitly asked to perform maintenance.

{}

Maintenance and data-management tools

eden_prune

Scoped bulk soft-delete (default) or hard-delete of memories. Runs as dry-run unless confirm: true and dry_run: false are passed.

{
  "org_id": "your-org",
  "workspace_id": "old-ws",
  "keywords": "deprecated",
  "expired_only": false,
  "dry_run": false,
  "confirm": true
}

Use hard: true with yes_i_really_want_to_delete: true for permanent deletion. Use org_empty, workspace_empty, agent_empty, or user_empty to match rows with empty/NULL scope values. See Prune old memories for a step-by-step guide.

eden_migrate

In-place remapping of org_id/workspace_id for a scope. Dry-run by default; requires confirm: true and dry_run: false to mutate. Set backup: true to copy the database first. See Migrate a workspace.

{
  "from_org_id": "your-org",
  "from_workspace_id": "old-ws",
  "to_org_id": "your-org",
  "to_workspace_id": "new-ws",
  "confirm": true,
  "dry_run": false
}

eden_packet

Build a deterministic, scope-bound knowledge packet for a single workspace. Never emits raw vectors.

{
  "format": "md",
  "template": "compact",
  "since": "2026-07-01T00:00:00Z",
  "limit": 50
}

Input fields:

Field	Type	Default	Description
format	string	json	Output format: json, md, or html.
template	string	default	Consumer template: default, compact, analytical, or full.
include_content	boolean	false	Emit full memory contents instead of excerpts. Adds a privacy warning.
since	string	—	RFC3339 timestamp; only include memories created or updated at or after this time.
limit	integer	50	Maximum memories to include. The compact template defaults to 10.
enrich	string	—	Optional enrichment pass: cluster. The analytical template defaults to cluster.
org_id	string	EDEN_ORG_ID env	Organization scope. Required if not configured.
workspace_id	string	EDEN_WORKSPACE_ID env	Workspace scope. Required if not configured.

Response shape:

{
  "format": "md",
  "packet": "# Knowledge Brief\n\n...",
  "warnings": [
    "Full memory contents are included in this packet. Share it only with trusted consumers."
  ]
}

• format echoes the requested format.
• packet is the rendered output as a single string.
• warnings is empty unless full contents are emitted, in which case it contains the privacy warning.

Templates and defaults:

Template	Excerpt length	Default limit	Enrichment	Notes
default	120 runes	50	—	Balanced stats + excerpts + optional clusters.
compact	80 runes	10	—	Omits per-memory metadata; title is “Knowledge Brief”.
analytical	120 runes	50	cluster	Omits per-memory metadata; emphasizes semantic clusters.
full	full content	50	—	Sets include_content=true automatically.

The canonical JSON packet uses schema version 1.1.0. Excerpts are deterministic: most recently updated memories appear first, then ties are broken by memory ID. Clusters, when enabled, are derived from scoped vector similarity using a 0.75 cosine threshold and a cap of eight clusters. No raw embeddings are ever included.

See Knowledge packets and Build a knowledge packet for more detail.

eden_export_snapshot

Export an encrypted AES-256-GCM + scrypt snapshot of the database. See Back up and restore a database.

{
  "path": "/path/to/backup.bin",
  "passphrase": "a strong passphrase"
}

eden_import_snapshot

Import an encrypted snapshot, replacing the current database. Requires both confirmations. See Back up and restore a database.

{
  "path": "/path/to/backup.bin",
  "passphrase": "a strong passphrase",
  "confirm": true,
  "yes_i_really_want_to_replace": true
}

Sync, pairing, and relay tools

These tools were added to support multi-device sync. See the multi-device sync guide for a map, the Sync two devices with a relay tutorial, and How sync works for protocol details.

eden_sync

One-shot bidirectional sync with a peer database via DirectTransport. Requires peer_db_path and confirm: true because pushing mutates the peer.

{
  "peer_db_path": "/path/to/peer.db",
  "peer_device_id": "optional-device-id",
  "batch_size": 1000,
  "confirm": true
}

eden_pair_device

Pair the local store with a peer database using in-process SPAKE2. Stores pinned peer public keys in both stores.

{
  "peer_db_path": "/path/to/peer.db",
  "account_id": "your-account",
  "password": "shared-secret",
  "confirm": true
}

Use dry_run: true to preview without writing peer records.

eden_sync_loop

Start, stop, run once, or check status of the background relay sync loop.

{
  "action": "start",
  "relay_url": "http://relay.example.com:8787",
  "account_id": "your-account",
  "passphrase": "root-key-passphrase",
  "interval_ms": 30000,
  "batch_size": 1000,
  "confirm": true
}

• action: start, stop, status, or once.
• start requires relay_url, account_id, and a root-key passphrase.
• passphrase falls back to EDEN_ROOT_KEY_PASSPHRASE in the server environment.

eden_relay_server

Start or stop a local HTTP relay server.

{
  "action": "start",
  "addr": ":8787",
  "relay_db_path": "/path/to/relay.db",
  "confirm": true
}

• action: start, stop, or status.
• start requires relay_db_path.

eden_relay_register

Register the current device with a relay directory so peers can discover it.

{
  "relay_url": "http://relay.example.com:8787",
  "account_id": "your-account",
  "passphrase": "root-key-passphrase",
  "confirm": true
}

eden_pair_create_invitation

Create a relay-mediated PAKE pairing invitation.

{
  "relay_url": "http://relay.example.com:8787",
  "account_id": "your-account",
  "password": "shared-secret",
  "passphrase": "root-key-passphrase",
  "confirm": true
}

The response includes an invitation_code to share out-of-band with the responder. dry_run: true previews without publishing an enrolment.

eden_pair_accept_invitation

Accept a relay-mediated PAKE pairing invitation. Persists the account root key sidecar and records the initiator as a peer.

{
  "code": "abc123...",
  "passphrase": "root-key-passphrase",
  "confirm": true
}

Use dry_run: true to preview without mutating the store or sidecar.

Usage tips

• Recall before deciding. Before answering a question about user preferences, recall first.
• Edit, don’t duplicate. When a fact changes, find the existing memory and edit it.
• Confirm mutations. Tools that write to a peer DB or perform bulk operations require confirm: true or default to dry-run.
• What not to store. Avoid secrets, command output, session IDs, and temporary state.
• Housekeeping is manual. eden_forget_expired, eden_vacuum, eden_prune, and sync-loop management are admin tools, not automatic routines.