Using memory effectively

Namespaces, importance, when to put vs. let auto-extraction work, and the patterns that compound.

Jettson Memory is the feature that makes agents get better over time. This guide is the playbook for using it well.

The mental model

Memory is user-scoped (every agent for the same user shares it), structured (namespaces + tags + importance), and searchable by meaning. The Mind reads memory at the start of every run automatically — your job is to make sure useful things land in there.

When to use what

| You want… | Use | | --- | --- | | The agent to look up specific facts mid-run | jettson_memory_search in the prompt | | The agent to remember a specific fact mid-run | jettson_memory_put in the prompt | | The agent to learn organically from its runs | Auto-extraction (no code) | | Cached results across runs (research, scrapes) | Explicit put with expires_in_days | | House rules / style guides | Seed memory via the API before any agent runs | | Bulk historical data | POST /api/v1/memory/import |

Namespaces — pick wisely, keep them stable

Namespaces scope search. Pick names you can live with for a year — renaming retroactively is a hassle.

Good namespaces:

  • customers — facts about specific customers
  • coding_standards — team style preferences (used by the PR reviewer)
  • research — cached company dossiers (used by customer research)
  • user_profile — personal preferences (brand color, tone, etc.)
  • system_prompts — reusable prompt fragments

Bad namespaces:

  • default for everything — search noise compounds fast
  • temp / scratch — if it's temporary, don't write it
  • One namespace per agent type AND one per task type — over-segmentation makes search useless

Importance — calibrate, don't max-out

Importance is 1-10. The default is 5; auto-extraction picks 6-8 for things it thinks are worth remembering. Some discipline:

  • 9-10: Inviolable rules. "Customer X is in EU jurisdiction — never send their data to US-only services."
  • 7-8: Strong preferences. Team coding standards, brand voice, "we ship on Tuesdays."
  • 5-6: Useful context. Default.
  • 2-4: Background color. The Mind sees it but only if other signals don't dominate.
  • 1: Don't bother — if it's importance 1, just don't write it.

When to call jettson_memory_put explicitly

Auto-extraction does a lot of the work for you. Use explicit puts when:

  • You need a specific shape. Auto-extraction picks the key and value. If you want key=customer_<id>_billing_history, you have to write it yourself.
  • You're caching a structured artifact. Customer dossier, research findings, computed configuration.
  • You want a non-default expires_in_days. Caches go stale; set a TTL.

A useful pattern in agent prompts:

text
After producing the final answer, ALSO do these writes:
- jettson_memory_put with namespace=research, key=<canonical-domain>,
  value=<JSON dossier>, importance=8, expires_in_days=30
- jettson_memory_put with namespace=user_profile, key=preferred_tone,
  value=<observed tone from this run>, importance=6 (only if you observed something concrete)

Dedup + consolidate — when to run them

After heavy use, the memory pool gets noisy. Two operations clean it up:

  • Dedupe — finds near-identical memories (cosine similarity ≥ 0.92 by default) and soft-deletes the less-accessed copy. Cheap. Run it weekly via cron or button.
  • Consolidate — clusters related memories and folds each cluster into a Mind-generated summary. Uses tokens. Run it once a month, or when the pool feels muddled.

Anti-patterns

The things you'll be tempted to do but shouldn't:

  • Storing PII or secrets. Memory is read by the Mind and visible in the Console. Don't put API keys or full credit cards in there.
  • Storing things that change frequently. Stock prices, weather, queue lengths. Time decay helps but doesn't save you.
  • Oversized values. The 5,000-char cap is generous; if you're hitting it, you're probably trying to store something that should live in /workspace or a real database.
  • Writing memories for every tool result. Be selective — the Mind decides what's useful, your prompt decides what's worth the importance ceremony.
  • One namespace. Search results turn into noise. Pick 3-5 namespaces.

Patterns that compound

The "research cache" pattern:

text
Step 1: Search memory namespace=research with key=<target-domain>
Step 2: If hit AND created_at < 30 days ago: return cached
Step 3: Else: do the research, then put under same key

Run a hundred research tasks and you've built a custom CRM at zero marginal cost.

The "team standards" pattern:

text
Step 1: Search namespace=coding_standards for relevant patterns
Step 2: Use them as house rules in the review
Step 3: For new patterns observed (and not in memory): put with importance=7

After ~10 PRs the agent stops re-flagging things your team has already accepted.

The "customer continuity" pattern:

text
Step 1: Get memory namespace=customers, key=<customer_id>
Step 2: Apply the tone + preferences from that record
Step 3: After the interaction, update or put with new observations

A six-month-old customer support agent has institutional memory the human team wishes it had.

Related