I reverse-engineered Instinct's memory. Here's exactly how it works

Instinct has taken the world by storm over the last two weeks — it's one of the best iMessage assistants I've used. As with every product, I decided to reverse-engineer Instinct's memory to find out exactly how it works.

I've been working on agent memory for the last 3 years, and I'm the founder of supermemory. The industry is constantly changing and there's no right answer to "how to do agent memory". Each product has different needs and constraints. Surprisingly, Instinct's memory aligns with our views of memory, and you can fully replicate it with supermemory — how-to at the end.

Because I've been doing this for so long, I have somewhat of a good intuition of how memory systems typically work, so I can reverse-engineer memory systems by just probing on the surface of the agent (the iMessage interface).

This is gonna be a bit long.

Instinct is powered by git-tracked markdown files

At its core, the memories are stored as git-tracked markdown files, but with a lot of harness-specific engineering done to make it seamless and fast.

The answering model (likely an open-weights model) receives:

• Current conversation context
• An identity "profile" of the user
• A memory one-pager (of what's going on)
• A compaction recap
• A to-do / tasks board

Conversation messages ────────────────→ Current conversation context
        │                                         │
        └→ Background processing [unknown]         │
                      │                           │
             Accessible Markdown files            │
                 │              │                 │
       One-pager generation     Search / reads    │
       [mechanism unknown]      [on demand]       │
                 │              │                 │
                 └──────────────┴─────────────────┤
Identity profile + todo index + compaction recap ─┤
                                                  ↓
                                            Agent's answer

Caveat

We reconstructed this by a lot of probing with questions, navigating through general assumptions and then trying to verify them. Most of it should be correct, but because I haven't seen their code, some things may be wrong.

Apart from the files, Instinct has about 4,250 tokens of somewhat of a "profile" and ~10k tokens of compacted conversation context (which, obviously, depends on the conversation).

So let's start there.

Profile and memory one-pager

A profile is essentially a gist of what the model always needs to know about the user. Instinct's profile has:

• Life context: a summary of selected user circumstances and relevant people or work.
• Autonomy calibration: selected preferences about when the assistant should act or ask.
• Channel communication style: selected preferences about how to communicate.

These are the "headers" that Instinct sees.

PS: supermemory has profiles built in — see user profiles — and has the same learnings. We split it into static and dynamic parts of the profile.

How are these profiles formed?

The best-supported reconstruction I could find is a derived summary of saved records. We do not know whether the generator reads all files, changed files, search results, earlier summaries, or independently stored facts. The generator (or dreaming, or learning) model, prompt, scheduling, conflict handling and response to forget requests all remain unknown.

A complete one-pager backing file was not found in the agent's accessible copy; that does not establish where it is actually stored. So this profile is likely not a file, but just an ad-hoc created cache of sorts.

This profile is also not kept very fresh. In some cases I was able to find a 2-day profile lag, but because there are dates in it, the agent is able to assume that it's not fully trustable.

In supermemory, the profiles are formed automatically and always kept fresh.

The files and folders

Now let's come to the file structure that Instinct uses. In my few days of using it, here's the file structure it came up with:

I was able to find a lot of redundant, stale or duplicate information, but that likely just helps the agent find the answer better.

Instinct reported that commit 899f88a added the preference to a communications digest, daily timeline and dining note. The README described raw, hourly and monthly timeline tiers, but those directories were absent from its accessible copy.

File structures

Files reportedly use structured headers followed by prose and bullets. This is an illustrative example:

---
id: dining
type: preference
aliases: [food, lunch, restaurants, takeout, delivery, dining]
---
- **Pasta:** Loves pasta; stated on 2026-09-15.
- Related context: [[related-record-id]]

A few things stand out from the file structure:

• Files have names, but also IDs.
• There are about 4 types in my account: preference, person, organization and conversation.
• Information itself is in the form of a list of facts, despite it being in a file.
• [[links]] connect related files, by ID.

So yes, it's a densely interconnected set of files, and the links make it graph-like.

Aliases are included — we'll get to why in the harness-specific stuff later.

Creating, updating, organizing info

It seems like the reconciliation commits do more than just append information:

• Move temporary details into workstreams.
• Shorten durable records while linking to fuller notes.
• Turn examples into broader traits.
• Remove incidental details.
• Replace incorrect facts with dated corrections.

Versioning

Old information can remain in git history. It can also remain in a dated note even after a current fact file changes. This info can only be brought back if the model explicitly looks for older versions.

supermemory's ingestion works in a similar way, and is done by a specialized model. We also automatically include old versions, so the model doesn't have to look for them.

Forgetting

Instinct does forget things based on when the ingestion runs, but this is not "automatic" right now.

So an explicit "this is not happening" will be forgotten, but "I have my exams this weekend" will remain in the records, unless the model looks at it and chooses to remove it.

supermemory has forgetfulness embedded into the system, so things automatically forget and evolve instead of an agent having to do it.

When does ingestion even happen?

Right now the ingestion works once every 24 hours. I'm assuming this because a preference took approximately 23 hours 16 minutes from message to reported commit. By the way, if you text Instinct too much in 24 hours it will quite literally tell you to come back tomorrow, since you can't compact beyond a certain token threshold.

So it's likely a cron job running every day to maintain the set of files and edit the current ones.

Harness: bringing memory to the agent

Ok, so now we know how Instinct arranges the files. But how is the agent actually using this info?

There's no vector indexing, or BM25 search

Instinct quite literally just uses keyword matching / grep-style queries to look things up in the file system. This is why every file has aliases associated, so that every file has a good chance of showing up when the agent is looking for it.

I found out by running multiple different queries in different ways.

Full structure

Instinct seems to be using bash-like tools to do grep, list and inspect git, plus a few tools to manage its todo list.

1. At the start of the conversation, a profile is injected.
2. Instinct makes use of the tools available to look up more information. A part of the profile is an index for the available things.

Memory is read-only, at least for the agent.

This is something I'm personally a big believer in. A background process does the work of combining things, not the main agent.

Performance of Instinct's memory

It's hard to benchmark from the agent surface, but here's my vibe-test rubric for Instinct's memory:

On write-side cost: we know writes will get exponentially more expensive for the agent to work through, as it has to read through current info to write more info, and consolidate and manage things. This should be fine for the personal agent use case, but we're not sure yet.

Overall: capable under explicit retrieval instructions, inconsistent in natural personalization, with forgetting guarantees unresolved.

Really, really good.

Implementing it with supermemory

There are some benefits to using supermemory here, and it is actually super obvious to implement.

1. Buckets for entities and relationships. supermemory supports profile buckets. Each user can get their own set of buckets, which is dynamic. This is like having a folder of info that the LLM can access — see profile buckets.
2. Profile at the start of the conversation. supermemory has a profile system built in, so that would be included at the start.
3. Search tools. Give the agent search tools, with a few specific options like including forgotten memories and history, in case it needs those — see search memory entries.
4. Ingest every 1-day conversation. An Instinct-like interface would run memories.add() every turn, with the current day being the ID of the conversation. supermemory's ingestion automatically handles forgetfulness, reconciliation and conflict resolution — see dreaming keeps the graph alive. It also automatically handles multi-modal ingestion.

supermemory is specialized towards memory, so it is much cheaper to run and much faster, while being fully composable at the same time. Instead of git, we have our own versioning system that's embedded with our data structure. Instead of full files, we construct files on demand, which also makes sure that info is always fresh.

Below is the full Instinct memory system, in supermemory, working almost exactly like Instinct. Just 60 lines of code.

import { streamText, tool } from "ai";
import { openai } from "@ai-sdk/openai";
import { withSupermemory, searchMemoriesTool, addMemoryTool } from "@supermemory/tools/ai-sdk";
import { z } from "zod";

const API_KEY = process.env.SUPERMEMORY_API_KEY!;
const userId = "user_alex";                            // containerTag — stable per user
const todayId = new Date().toISOString().slice(0, 10); // e.g. "2026-09-20"

// 1. Profile injected automatically at the start of every turn (static + dynamic + buckets)
const model = withSupermemory(openai("gpt-5"), {
  containerTag: userId,
  customId: todayId, // one document per day -> ingest every 1-day conversation
  mode: "full",      // profile + query search
});

// 2. Dynamic bucket tools: list existing buckets, create new ones on the fly
const listBucketsTool = tool({
  description: "List the profile buckets configured for this user",
  inputSchema: z.object({}),
  execute: async () => {
    const res = await fetch("https://api.supermemory.ai/v4/profile/buckets", {
      method: "POST",
      headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({ containerTag: userId }),
    });
    return res.json(); // { buckets: [{ key, description }, ...] }
  },
});

const createBucketTool = tool({
  description: "Create or add a new topical bucket for this user's profile (space-level, additive)",
  inputSchema: z.object({
    key: z.string().describe("lowercase slug, letters/digits/-/_ only"),
    description: z.string().optional(),
  }),
  execute: async ({ key, description }) => {
    const res = await fetch(`https://api.supermemory.ai/v3/container-tags/${userId}`, {
      method: "PATCH",
      headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({ profileBuckets: [{ key, description }] }),
    });
    return res.json();
  },
});

// 3. Search tool with forgotten/history options exposed to the agent
const searchTool = searchMemoriesTool(API_KEY, {
  containerTag: userId,
  // lets the agent opt into forgotten memories / relationship history when needed
});

const result = await streamText({
  model,
  prompt: "What buckets do we have for me, and what's changed recently?",
  tools: {
    listBuckets: listBucketsTool,
    createBucket: createBucketTool,
    searchMemories: searchTool,
    addMemory: addMemoryTool(API_KEY, { containerTag: userId }),
  },
});

So yes — that's how Instinct's memory works, and how you can implement Instinct's memory system with supermemory completely.