# Five entry types that belong in your AI agent's memory file

> Source: <https://dev.to/karmabox/five-entry-types-that-belong-in-your-ai-agents-memory-file-n24>
> Published: 2026-11-19 04:00:39+00:00

**Recommendation:** Keep agent memory in a versioned file you own, tagging corrections with lifecycle fields and marking episodic summaries as compression, so a model switch doesn't require re-teaching.
More in the playbook "Designing agent systems": <https://wpnews.pro/playbooks/agent-architecture>

Most engineering teams version their prompts now. Very few version what the agent has learned since: the corrections, the house rules, the "we tried that in March, it broke billing" warnings that accumulate in daily use. Prompts are code. Accumulated memory is state. Teams that treat state as something the vendor will look after tend to discover the difference during a migration.

This matters more in a week like this one. OpenAI shipped GPT-6.2 Astra and Sol on November 17, Google followed with Gemini 4 Neon on November 18, and Microsoft announced MAI Code 2 in the same 48 hours. Whether you should chase any of them is a separate question (we wrote about [the difference between an avatar and a model](https://www.karmaboxai.com/en/concept/factory/resources/ai-avatar-vs-ai-model) earlier this month). This post is about the narrower engineering problem: if you did switch, what file would you carry over, and would you trust what's in it?

AI memory portability is the ability to move what an assistant has learned, the facts, corrections, preferences and project context it accumulated, onto a different model or runtime without re-teaching it. It is a property of where the memory lives, not of how capable the model is. A memory that lives in a file you hold survives any switch. A memory that lives anywhere else survives some switches and not others, and the difference is decided by format, not by luck.

So let's talk about the file.

Every major assistant lets you export your conversation history, usually as JSON or HTML. That export is useful. It is also not a memory file. It is a transcript: every instruction you ever gave, including the ones you reversed a week later, with nothing marking which one won.

Suppose you told the agent in June that invoices go out on the 25th, and in September that they now go out on the 1st. The transcript contains both sentences with equal weight. A new model reading that transcript has to re-derive the current rule from timestamps and context, which is exactly the re-teaching work the file was supposed to spare you.

A memory file is the distilled version: current state, with history attached as metadata rather than as the payload. The distinction sounds obvious written down. Almost no export format on the market today produces it.

After a year of running agents on our own infrastructure, the entries that earn their place in the file sort into five types. (The taxonomy follows what gets lost in practice, which we walked through in [agent memory ownership](https://www.karmaboxai.com/en/concept/factory/resources/ai-agent-memory-ownership); here we only care about structure.)

**Stable facts and preferences.** "Reply to customers in German." "The owner's timezone is UTC+8." Low churn, high value, trivially portable as plain statements.

**Corrections.** "The payments repo signs webhooks with the legacy key, not the one in `.env.example.`" This is the type that hurts most to lose, because each one was paid for with a debugging session. Corrections are also the type most likely to be superseded later, so they need lifecycle fields.

**Project and business context. **Current clients, price floors, naming conventions, who approves what. Changes monthly rather than yearly. Often lives half in the agent's memory and half in documents, which is fine as long as the memory entry points at the document instead of paraphrasing it.

**Episodic summaries.** Compressed accounts of what happened: "Week 32: migrated the staging cluster, two rollbacks, root cause was the pinned driver." Useful for continuity, dangerous when they silently become the only record. Keep them, but mark them as summaries so nobody mistakes compression for evidence.

**Derived data. **Embedding vectors, retrieval indexes, caches. This type goes in the file's manifest but never counts as the asset itself, for reasons the re-indexing section will make concrete. If your export contains vectors but not the source text they were computed from, you have exported the derived cache and left the actual asset behind.

One schema that has held up for us:

```
{
  "id": "mem_2026_0412",
  "type": "correction",
  "statement": "Payments repo signs webhooks with the legacy key, not the one in .env.example.",
  "scope": "repo:payments",
  "taught_by": "zoe",
  "taught_at": "2026-08-14T09:12:00Z",
  "status": "active",
  "supersedes": "mem_2026_0291",
  "review_after": "2027-02-01",
  "source_refs": ["chat:2026-08-14#t142"]
}
```

Three of these fields do the portability work, and they are precisely the ones a chat export lacks.

`status` plus `supersedes` encode which version of a rule is current, so a new model never has to re-litigate your history. `taught_by` and `taught_at` are provenance: when two entries conflict, you can resolve by authority and recency instead of guessing. `scope` keeps a correction about the payments repo from leaking into advice about the analytics repo, which is the single most common failure we see when memory gets injected wholesale into a context window.

`review_after` is optional and underrated. Memory that can expire gracefully stays trustworthy; memory that only accumulates eventually poisons retrieval with stale rules.

Credentials, API keys, session tokens: never memory entries. They rotate on a different schedule, they have different access control needs, and an exported memory file will travel to places a key must not. Keep secrets in a secret manager and let memory entries reference capabilities by name. (Identity and credentials deserve their own treatment, which the [agent identity](https://www.karmaboxai.com/en/concept/factory/resources/ai-agent-identity-sovereignty) piece covers.)

Raw conversation logs stay out too, for the superseding reason above. So do model-specific prompt tricks. If an entry only works because one particular model interprets a phrasing quirk a certain way, it is configuration for that model, not knowledge about your business. Tag it as such or accept that it dies in the move.

The format we have settled on is deliberately boring: one JSONL file for the entries, one Markdown mirror for humans, one manifest.

```
memory-export/
  entries.jsonl        # one entry per line, schema above
  entries.md           # same content, grouped by scope, human-readable
  manifest.json        # counts, date range, schema version, index fingerprints
```

JSONL instead of one big JSON array because it diffs, streams and merges line by line. The Markdown mirror exists because the person auditing a migration at 11 p.m. is not going to read JSONL, and because a second representation catches serialization bugs (if the two disagree, the export is broken). The manifest records what embedding model the current indexes were built with, which turns the re-indexing step from archaeology into a checklist item.

The whole directory belongs in version control. A diff of `entries.jsonl` reads as a changelog of what the team taught the agent that week, and a memory change that goes through review catches a surprising number of wrong or overly broad rules before they calcify. If your team already reviews prompt changes, this is the same muscle pointed at state.

To be fair to the hosted platforms: account-level memory on the major assistants does persist across that vendor's own model updates. If you moved from one model version to the next inside the same product this week, your saved memories came along. The file earns its keep at the boundaries vendors do not cross for you: moving to a different vendor, moving to a different runtime (cloud to local, or onto your own hardware), and proving after the move that nothing silently changed.

A memory file that only ever has one writer is the easy case. The day a teammate runs the same avatar on their machine, or a staging copy learns something production should know, you have two files that must become one, and the format either planned for this or it didn't.

Line-oriented JSONL gets you halfway: concatenate, then deduplicate by `id`. The other half is conflict resolution, and the fields from the schema earn their keep again. Two entries with the same scope and contradictory statements resolve by `taught_at` recency unless one `supersedes` the other explicitly; entries from different scopes never conflict by definition, which is a quiet argument for keeping scopes narrow. When recency and authority disagree (the older entry came from the owner, the newer one from an intern's session), the merge tool should stop and ask rather than pick. A merge that needs zero human decisions is usually a merge that silently lost one.

Deletions need special handling. If you remove an entry from one copy and merge with a copy that still has it, the entry comes back. The standard fix is a tombstone: the entry stays in the file with `status: "retracted"` and an empty statement, so the deletion itself propagates. Memory that can be deleted everywhere, provably, matters more than it sounds; the moment memory contains anything about people, retraction stops being a nicety and becomes an obligation (the [company-side ownership questions](https://www.karmaboxai.com/en/concept/factory/resources/who-owns-ai-agent-memory-company) make the same point from the offboarding angle).

A file on disk teaches the model nothing. At runtime, something has to decide which entries ride along with each request, and this injection policy is as much a part of portability as the schema, because it is what the new model actually experiences.

The pattern that has survived contact with our own usage is two tiers. A small always-on core, stable facts and preferences, rides with every request. Everything else is retrieved per task, filtered by scope first and similarity second. The scope filter runs before the vector search, which is what keeps a payments correction from surfacing in an analytics task even when the two texts embed close to each other.

The budget math is worth doing explicitly, because memory competes with the actual task for context. Forty always-on entries at an average 25 tokens each is 1,000 tokens on every call (that assumption counts the statement text only; formatting overhead adds maybe a fifth). At ten thousand calls a month that is ten million tokens of standing overhead before anyone asks a question. The lesson we took: promotion to the always-on tier should be rare and audited, and an entry that has not been retrieved in months is a candidate for archive, not for a bigger core. The file can afford to be a warehouse. The context window cannot.

Two tiers also simplify migration testing. The always-on core is small enough to eyeball in the new binding's first system prompt; the retrieved tier is exactly what the golden set exercises question by question.

An embedding is the list of numbers a model assigns to a piece of text so that similar texts get nearby numbers; retrieval works by comparing distances between these coordinates. The part that bites people: the coordinates are only meaningful inside the model that produced them. Two embedding models are two different coordinate systems, and a distance measured between a point from each is noise, even when the models come from the same family one version apart.

So if you switch embedding models and keep the old index, retrieval does not fail loudly. It degrades into confident nonsense: queries embedded in the new space are compared against stored vectors from the old space, and the nearest neighbors are near by accident.

*Example scenario: a 200-query retrieval check against the same memory store (top-5 hit rate; the figures illustrate the mechanism, not a benchmark). The middle bar is the trap: nothing errors, results just quietly stop matching.*

The engineering consequences are short:

Re-embedding is cheap relative to the damage of skipping it. Ten thousand entries averaging 60 tokens is roughly 600k tokens of embedding work (one pass, no retries assumed), which current hosted embedding APIs price in cents and a local model does for electricity. The deeper cost of hosted embeddings is schedule, since a deprecation notice forces the re-index on the vendor's calendar. Pinning an open-weight embedding model on your own hardware moves that onto yours, and the local menu keeps improving, with Radixark's DaisyRose-27B (released November 18) the latest open-weight entrant in a week otherwise dominated by closed flagship launches.

Format gets memory across; verification proves it arrived. The cheapest instrument we know is a golden set: ten questions whose answers depend on specific memory entries and can be checked mechanically.

Good golden questions have crisp expected answers. "Which key signs webhooks in the payments repo?" is checkable. "Summarize our deployment philosophy" is not. Pull one question from each scope that matters, bias toward corrections (the expensive type), and store expected answers next to the questions:

```
# golden_set.yaml
- id: g01
  question: "Which signing key do webhooks in the payments repo use?"
  expect_contains: ["legacy key"]
  depends_on: ["mem_2026_0412"]
- id: g02
  question: "What day do invoices go out?"
  expect_contains: ["1st"]
  depends_on: ["mem_2026_0533"]
python
# verify.py (sketch)
import yaml

golden = yaml.safe_load(open("golden_set.yaml"))
failures = []
for g in golden:
    answer = ask_new_binding(g["question"])   # your client here
    if not all(s.lower() in answer.lower() for s in g["expect_contains"]):
        failures.append((g["id"], answer[:120]))
print(f"{len(golden) - len(failures)}/{len(golden)} passed")
for fid, preview in failures:
    print("FAIL", fid, "->", preview)
```

Run it three times: against the old binding (to prove the questions are answerable at all), against the new binding on day one, and again after fixes. Expect the middle run to find something.

*Example scenario: in our runs the day-one failures are rarely lost entries. They are entries the new model reads differently, a date format here, an implicit unit there. Cheap to fix once named, invisible until asked.*

When a question fails, triage it into one of three buckets before touching anything, because the fixes point in different directions. If the entry is missing from the store, the export or merge dropped it: a format problem, fix the pipeline and re-import. If the entry is present and retrieved but the answer is wrong, the new model is misreading the statement: a phrasing problem, rewrite the entry to be model-agnostic (spell out units, use ISO dates, avoid pronouns) and add the old phrasing to a regression note. If the entry is present but never retrieved, the new embedding space ranks it differently: a retrieval problem, check the re-index actually ran and consider widening the scope filter before blaming the model. In our experience the second bucket dominates, which is good news, since rewriting a handful of statements is an afternoon, and every rewrite makes the file more portable for the switch after this one.

Keep the old binding alive for a week after the switch. A golden set catches what you thought to test; the week catches what you didn't.

Our own product, KarmaBox, is built on the premise this post argues for: an avatar's memory lives in a file on a machine you own, and the model is the replaceable part. Here is how each problem above maps onto something you can configure, with the dates of what we have published.

The portable file itself is the default, not an export feature. Each [AI avatar](https://www.karmaboxai.com/en/concept/factory/ai-avatar) keeps its accumulated memory in a file that travels with it, and since the unified re-embodiment release (2026-10-24) the same avatar moves between cloud, a Mac and a [KarmaBox device](https://www.karmaboxai.com/en/concept/factory/product) with its memory intact, no retraining step. The setting that matters to you: back the memory file up to your own disk on whatever schedule you back up code.

Model switching is decoupled from key juggling. Cloud models are built into the platform, so trying this week's releases does not mean provisioning new API keys; when a task would spend money on a cloud model, the avatar asks first and waits for approval. That turns "should we try the new flagship" from an infrastructure ticket into a yes/no decision, with the memory file constant across the comparison.

The on-device claim is measured, not asserted. In our published unplugged test (2026-10-28 to 30, network cable out), one device ran 197 local inferences in a day with zero business data leaving the machine, and its 886 conversations, 2 knowledge bases and 24 memory entries stayed readable on the device page, which reports "nothing has left". The full setup is documented under [what a sovereign AI avatar is](https://www.karmaboxai.com/en/concept/factory/resources/what-is-sovereign-ai-avatar). The point for this post: a memory file you can read while offline is a memory file whose location you do not have to take on faith.

And the golden-set habit has a live example. In an internal test of our cross-border commerce avatar team (2026-11-15, test account), an avatar that had been taught a cost structure once answered a single instruction with the full landed-profit calculation, $12.55 per unit, break-even ACoS 41.84%, in 28 seconds, matching a manual recalculation. A question like that, specific, numeric, checkable, is exactly what belongs in a migration golden set.

What should you do if you run your stack somewhere else entirely? Everything above the product section works without us: the schema, the JSONL export, the manifest fingerprint, the golden set. The file format is the portability. We would rather you have it anywhere than lose it everywhere.

A clean migration proves your memory arrived. It does not make the new model better at using it. Capability differences between models are real, tone differences survive no file format, and the re-embedding pass costs time even when it costs little money. We call the remaining exposure re-validation cost: after any switch you still owe a period of watching outputs more closely, golden set or not, because the file carries what the agent knows, never how the new model will behave with it.

Budget for that week. It is much smaller than re-teaching six months of corrections, which is the alternative on offer.

If you had to rebind your agent to a different model next Monday, how many of its memories could you prove survived by lunch?

OpenAI, [Introducing GPT-6.2 Astra and Sol](https://openai.com/index/introducing-gpt-6-2-astra-sol/), 2026-11-17

Google, [Introducing Gemini 4 Neon](https://blog.google/innovation-and-ai/models-and-research/gemini-models/introducing-gemini-4-neon/), 2026-11-18

Microsoft AI, [Introducing MAI Code 2 and MAI Code 2 Flash](https://microsoft.ai/news/introducing-mai-code-2-and-mai-code-2-flash/), 2026-11-17

Radixark, [DaisyRose-27B](https://www.radixark.com/blog/daisyrose-27b), 2026-11-18
