How memory works

The short version

FishMem is not a chat log. When you send a conversation turn to add, the engine doesn't just append text — it reads the turn, pulls out the facts worth remembering, decides how those facts relate to what it already knows, and commits the result to storage. The point is that next time you search, you get the current truth, not a transcript you have to re-read.

Every add runs three steps.

1. Extract

The engine sends your messages through an extraction pass (a gpt-4o-mini-class model) that turns loose conversational text into durable atomic facts. "I just moved to Berlin for the new job, loving it so far" becomes something like a single fact: the user lives in Berlin. Chit-chat, hedging, and one-off remarks that aren't worth remembering are dropped.

Each extracted fact is embedded with text-embedding-3-small so it can be recalled later by meaning, not just exact words.

2. Reconcile

New facts rarely arrive into an empty store. The engine pulls the existing memories that are semantically close to each candidate fact and decides what should happen. Every candidate resolves to one of four events:

• ADD — genuinely new information, stored as a fresh memory.
• UPDATE — refines an existing memory (more specific, corrected detail).
• INVALIDATE — contradicts an existing memory; the old one is superseded (not deleted — see bi-temporal facts).
• NOOP — already known; nothing changes.

This is the step that keeps the store coherent over time instead of accumulating duplicates and contradictions.

3. Store

Surviving facts are written to a hybrid store: a graph store (Cloudflare D1) that holds the facts, their entities, and the relationships between them, plus a vector index (Vectorize) that holds the embeddings for similarity search. Keeping both lets recall combine meaning-based search with graph traversal across connected entities.

Skipping extraction

Sometimes you don't want any of this — you have content that should be stored verbatim (a raw document, a structured note, a system message). Pass infer: false on add and the engine skips extraction and reconciliation entirely, storing the content as-is. You still get embeddings and search, just no fact distillation.

Next

• Bi-temporal facts — why invalidated memories stay queryable.
• Hybrid recall — how the four search signals combine at read time.