Memory API

Read, write, search, dedupe, consolidate, export, import — the full Jettson Memory surface.

Memory belongs to the user. Every endpoint below scopes to the API key's owner — there's no cross-account leakage and no need to pass a userId.

For the conceptual model see Memory.

Put a memory

POST/api/v1/memory

Create or version-update a memory. Idempotent on identical (key, namespace, value).

| Field | Type | Description | | --- | --- | --- | | key (required) | string | Short snake_case identifier, unique per namespace. | | value (required) | string | Up to 5,000 characters. Plain text — stringify JSON if structured. | | namespace | string | Logical bucket (default default). | | tags | string[] | Up to 20 tags, each up to 50 chars. | | importance | number (1-10) | Higher = ranks higher in search (default 5). | | expires_in_days | number | If set, memory is excluded from search after this many days. |

bash
curl -X POST https://jettson.dev/api/v1/memory \
  -H "Authorization: Bearer $JETTSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "brand_color",
    "value": "Brand primary color is #FF5733",
    "namespace": "user_profile",
    "tags": ["brand", "design"],
    "importance": 8
  }'

Returns the created memory record (memory_id, all fields, created_at).

Get a memory

GET/api/v1/memory?key=&namespace=

Fetch a memory by (namespace, key). Bumps accessCount as a side effect.

bash
curl "https://jettson.dev/api/v1/memory?key=brand_color&namespace=user_profile" \
  -H "Authorization: Bearer $JETTSON_API_KEY"

Returns 404 with not_found if no live memory matches.

Delete a memory

DELETE/api/v1/memory?key=&namespace=&hard=false

Soft delete by default — sets isLatestVersion=false and stamps deletedAt. Pass hard=true to actually remove.

bash
curl -X DELETE "https://jettson.dev/api/v1/memory?key=stale_thing&namespace=research" \
  -H "Authorization: Bearer $JETTSON_API_KEY"

Search

POST/api/v1/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 this namespace if set. | | tags | string[] | AND-filter on these tags. | | limit | number | Max results (default 10, cap is 50). | | mode | 'hybrid' \| 'semantic' \| 'keyword' | Ranker mode (default hybrid). See the concept page for weights. | | min_score | number | Filter out results below this combined score 0-1 (default 0). |

bash
curl -X POST https://jettson.dev/api/v1/memory/search \
  -H "Authorization: Bearer $JETTSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what color is my brand",
    "namespace": "user_profile",
    "limit": 5
  }'

Response:

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

List

GET/api/v1/memory/list?namespace=&tags=a,b&limit=N

Page through live memories. No ranking — newest first.

Dedupe

POST/api/v1/memory/dedupe

Find near-duplicate memories (semantic similarity ≥ threshold) and soft-delete the less-useful copies.

| Field | Type | Description | | --- | --- | --- | | namespace | string | Restrict to one namespace, otherwise scan everything. | | threshold | number (0-1) | Cosine similarity above which two memories are "the same" (default 0.92). | | dry_run | boolean | If true, only report which pairs would be removed (default false). |

json
{
  "removed": 3,
  "kept": 42,
  "pairs": [
    { "kept": "mem_abc", "removed": "mem_xyz", "similarity": 0.94 }
  ]
}

Consolidate

POST/api/v1/memory/consolidate

Cluster related memories and fold each cluster into a single Mind-generated summary.

| Field | Type | Description | | --- | --- | --- | | namespace | string | Restrict to one namespace. | | min_cluster_size | number | Don't consolidate clusters smaller than this (default 3). | | threshold | number (0-1) | Semantic-similarity threshold for clustering (default 0.75). |

This call uses the Mind to write the summaries — it consumes tokens. Don't loop it.

Namespaces

GET/api/v1/memory/namespaces

List all of the user's namespaces with live-memory counts.

json
{
  "namespaces": [
    { "namespace": "research", "count": 42 },
    { "namespace": "coding_standards", "count": 15 },
    { "namespace": "default", "count": 7 }
  ]
}

Export

GET/api/v1/memory/export

Download every live memory as a JSON document. Round-trips through /import.

bash
curl https://jettson.dev/api/v1/memory/export \
  -H "Authorization: Bearer $JETTSON_API_KEY" \
  -o memory-export.json

Import

POST/api/v1/memory/import

Bulk insert memories (or restore from an export). Goes through putMemory, so versioning + quotas apply.

json
{
  "memories": [
    { "key": "brand_color", "value": "#FF5733", "namespace": "user_profile", "tags": ["brand"], "importance": 8 }
  ]
}

Returns { imported: N, failed: N, errors: [...] }. Quota exceeded mid-batch halts with HTTP 402.

Related