Memory tools

The five memory operations agents can call from inside a task — put, get, search, list, delete.

Memory tools are how an agent reads and writes long-term memory mid-run. They mirror the public memory API one-to-one, but from inside its computer the agent calls them as tools rather than HTTP — no auth boilerplate, no JSON wrapping.

For the data model and ranker details see the Memory concept page.

jettson_memory_put

Save a value to memory under key. Versioning and quota enforcement work the same way the public API does.

| Field | Type | Description | | --- | --- | --- | | key (required) | string | Short snake_case identifier, unique per namespace. | | value (required) | string | Up to 5,000 characters. | | namespace | string | Logical bucket (default default). | | tags | string[] | Up to 20 tags. | | importance | number (1-10) | Drives search ranking (default 5). | | expires_in_days | number | If set, memory expires after this many days. |

Returns:

json
{ "memory_id": "mem_...", "key": "...", "namespace": "..." }

jettson_memory_get

Fetch a specific memory by (namespace, key).

| Field | Type | Description | | --- | --- | --- | | key (required) | string | The memory key. | | namespace | string | Namespace (default default). |

Returns either:

json
{
  "found": true,
  "value": "...",
  "key": "...",
  "namespace": "...",
  "tags": ["..."],
  "importance": 7,
  "created_at": 1715712000000,
  "updated_at": 1715712000000,
  "access_count": 4
}

or { "found": false } if no live memory matches. The Mind always checks found before using the value.

jettson_memory_search

Hybrid semantic+keyword search across the user's memory pool.

| Field | Type | Description | | --- | --- | --- | | query (required) | string | Natural-language query. | | namespace | string | Restrict to one namespace if set. | | tags | string[] | AND-filter on these tags. | | limit | number | Max results (default 10, cap 50). | | mode | 'hybrid' \| 'semantic' \| 'keyword' | Ranker mode (default hybrid). |

Returns:

json
{
  "results": [
    {
      "key": "brand_color",
      "value": "Brand primary color is #FF5733",
      "namespace": "user_profile",
      "tags": ["brand", "design"],
      "importance": 8,
      "score": 0.82,
      "breakdown": { "semantic": 0.78, "keyword": 1.0, "importance": 0.8, "timeDecay": 0.97 },
      "created_at": 1715712000000
    }
  ]
}

jettson_memory_list

List live memories, optionally filtered. No relevance ranking — newest first.

| Field | Type | Description | | --- | --- | --- | | namespace | string | Restrict to one namespace. | | tags | string[] | AND-filter on these tags. | | limit | number | Max 200 (default 50). |

Useful when the agent wants to enumerate everything in a small namespace ("what brand-style memories do I have?").

jettson_memory_delete

Soft delete a memory. The doc keeps existing with isLatestVersion=false and a deletedAt stamp; search and get won't surface it.

| Field | Type | Description | | --- | --- | --- | | key (required) | string | Memory key. | | namespace | string | Namespace (default default). |

json
{ "deleted": true }

Hard delete is API-only (DELETE /api/v1/memory?hard=true) — agents can't permanently destroy memories from inside a run.

Failure modes

| Situation | Returns | | --- | --- | | Quota exceeded on write | error: "Jettson Memory failed: memory quota exceeded …" | | Validation failure (bad key, oversized value) | error: "Jettson Memory failed: …" | | Memory channel not configured (warm pool didn't inject token) | error: "Jettson Memory failed: memory channel is not configured." |

In every case the agent loop continues — the Mind sees the error and adapts (saves to a different key, returns a partial answer, etc.).

When agents put vs. auto-extract

Three modes:

  1. Auto-extraction (the default). Run an agent, finish, the Mind reviews the run and writes durably-useful memories with source: "auto_extracted". No jettson_memory_put calls needed.
  2. Explicit jettson_memory_put in the task prompt. Use when you want the agent to save specific things mid-run — e.g., "After researching, save the dossier under namespace=research, key=<domain>."
  3. Both. Most production agents do explicit puts for the structured data and let auto-extraction grab the cross-cutting insights.

Auto-extraction is what makes Jettson Memory feel magical without effort. Explicit puts are what you reach for when you want guarantees.

Related