How memory works

Two tools, a profile that solves the cold start, and a write path that merges duplicates and retires facts once they stop being true.

create_memory

One self-contained statement, written in the third person, one fact per memory.

Argument	Type	Notes
`content`	string, required	Up to 10,000 characters
`tags`	string[]	Lowercase labels for filtering, at most 20
`source`	string	Which assistant saved it; defaults to the client's User-Agent

search_memory

Semantic search, not keyword matching. "What database does billing use?" finds "The billing service runs on Postgres and Stripe" without sharing a word beyond billing.

Argument	Type	Notes
`query`	string	Natural language. Omit it entirely for the profile
`limit`	integer	1 to 50. Default 10 for a search, 20 for the profile
`tags`	string[]	Only memories carrying all of these tags
`min_score`	number	Drop results below this 0–1 similarity

Both tools return readable text for the model plus structuredContent with the records. create_memory also reports when a memory was already known and which outdated memories it replaced.

The profile: fixing the cold start

Semantic search only helps an assistant that already knows what to ask. So search_memory with no query returns your profile in a single call: pinned memories first, then the ones assistants recall most often, then the newest. Assistants are told to read it at the start of every conversation. It costs no embedding call and counts against no cap.

Pinning is the one lever worth pulling. Pin the handful of facts that should shape every answer — how you write, what you are building, who you work for. Everything else can be found by search when it is relevant.

Keeping memories good

Memory written by agents drifts: the same fact reworded five ways, an address from two moves ago, stale entries outranking fresh ones. GuardianMemory handles that at write time and at read time.

Near-duplicates merge

A new memory whose meaning sits within cosine 0.95 of an existing one is treated as the same fact. Nothing new is stored, the tags are merged, and the assistant is told. Exact repeats, ignoring case and whitespace, are caught before an embedding is even requested.

Contradictions retire the old fact

When a new memory is merely related — cosine 0.80 or above — Jev, TypeSafe AI's System One classifier, is asked one question per candidate: is this a duplicate, does it supersede the old one, or are they unrelated? Jev answers with calibrated probabilities in tens of milliseconds, and a verdict only counts above 0.6 probability, so a stale fact is kept rather than a true one wrongly retired.

Superseded memories keep their row. They leave search results and the profile, and show struck through in the app so you can see the history. Saving an outdated fact again, word for word, revives it.

Fresher wins ties

Search finds candidates by similarity, then reorders them with up to a 10% preference for newer memories that fades over about 90 days. The score reported to the assistant is the raw similarity, not the boosted one.

You can always fix it

Every memory can be edited — changed wording is re-embedded — pinned to the profile, or deleted outright. The Activity page shows exactly what each assistant searched for and saved.

Importing what your assistants already know

The Import page takes up to 500 memories at a time, as either:

one memory per line, with bullets, numbering and quotes stripped, or
a JSON list of strings, or of objects with a content, text, memory or value field.

Lines are embedded in batches and exact and near-duplicates are merged as they land. Each imported memory counts as one operation against your daily cap. Imports skip the Jev step, so nothing already in your bank is retired by a bulk paste.

What is not there

There is no forget_memory tool, on purpose. Two tools is the point, and an assistant that can delete is an assistant that can quietly lose things. Assistants retire outdated facts by saving the new version; deleting is a decision you make in the app.