# chat-recall guides

> Every guide on https://chatrecall.dev, in one file.

## Giving Claude Code memory with an MCP server

> Which file Claude Code reads, what the entry looks like, and the one key that makes a correctly configured server register and then expose no tools at all.

Source: https://chatrecall.dev/guides/claude-code-memory-mcp/
Published: 2026-09-24

### What Claude Code remembers without help

- Auto memory · Notes it writes to itself under the project, keyed to the git repository. One repo, one machine, one tool. [Where it stops](https://chatrecall.dev/guides/claude-code-auto-memory-limits/).

- CLAUDE.md · Standing rules you write deliberately, in version control, read at the start of a session.

- claude --continue · Reopens the last session in the current directory. Resumes; does not search.

None of the three answers a question about work you did last month, in another repository, in another tool. That gap is what a memory server is for, and it is why the assistant needs a tool it can call mid-task rather than a file it reads once at startup.

### Where the configuration lives

Claude Code reads MCP servers from two files, both keyed under `mcpServers`:

- ~/.mcp.json · The file most setup instructions mean. A project can carry its own `.mcp.json` as well.

- ~/.claude.json · User level, and also where Claude Code keeps its opt-outs, in `disabledMcpServers`.

### The entry

~/.mcp.json

```
{
  "mcpServers": {
    "chat-recall": {
      "command": "chat-recall-mcp"
    }
  }
}
```

Four keys are meaningful: `command`, an optional `args` array, an optional `env` object, and `alwaysAllow`, a list of read-only tools the client may call without asking each time. `npx chat-recall init` writes this for every AI tool it finds on the machine, merging into the file rather than replacing it, and it preserves an `alwaysAllow` list you have curated by hand.

### When it registers and no tools appear

This is the failure worth knowing about in advance, because every surface reports success.

An entry carrying `"disabled": true` reads as configured. Sweeping four MCP clients with deliberately broken shapes, all four answered that the server was already configured, and then no tools showed up in the session. Cursor and Antigravity honour that key and skip the server. Claude Code ignores it entirely, because its own opt-outs live in `disabledMcpServers` in `~/.claude.json` — so on Claude Code the key does nothing while still looking like the cause.

If the tools are missing, check three things in this order: the entry has no `disabled` key, the server name is absent from `disabledMcpServers`, and the file you edited is one of the two above.

what is actually wired up

```
$ chat-recall doctor
  login, server, credentials, hooks and the MCP server — per profile
```

Per profile matters: `CLAUDE_CONFIG_DIR` relocates the whole config root, so a second profile is a second set of everything.

### The other tools do not use this shape

Worth knowing if you are wiring more than one by hand, because copying the Claude entry across does not work:

- OpenCode · Keys servers under `mcp`, takes the command as an argv array, and needs `type: local` and `enabled: true` before it will spawn one.

- Codex · TOML. `~/.codex/config.toml`, under `[mcp_servers.<name>]`.

- Cursor, Antigravity · The same `mcpServers` shape, and both honour `disabled`.

### Which server to put there

That is a different question from this one, and the answer depends on whether you want facts you state on purpose or history you recover. [The three kinds of MCP memory server](https://chatrecall.dev/guides/mcp-memory-servers-compared/) is the comparison; [the tool list for this one](https://chatrecall.dev/mcp/) is what the assistant gets to call.

[Wire it up with one command](https://chatrecall.dev/app) [View the history you already have](https://chatrecall.dev/guides/claude-code-session-history-viewer/)

## How to view your Claude Code session history

> Claude Code keeps every session as a JSONL file on disk. Two built-in commands show you part of it, the files show you the rest, and neither one searches.

Source: https://chatrecall.dev/guides/claude-code-session-history-viewer/
Published: 2026-09-24

### The two commands that ship with it

- claude --continue · Reopens the most recent session in the directory you are standing in. No picker, no choice.

- claude --resume · Lists recent sessions for that same directory and lets you pick one.

Both are scoped to the current working directory. That is the single fact that explains most of what follows.

### Where the files are

One directory per project, one JSONL file per session, named by the session UUID:

on disk

```
~/.claude/projects/<project>/<session-uuid>.jsonl
```

The `<project>` segment is the working directory with every slash turned into a dash, so `/home/user/code/example` becomes `-home-user-code-example`. That naming is worth knowing, because it is why a renamed folder looks like lost history.

### Reading one by hand

Each line is one JSON event, so the file is readable with anything that speaks JSONL. Filter on the message records and print the role with the content, and you get the conversation without the tool traffic wrapped around it.

Claude Code keeps four more things beside the transcript, and people usually only discover them when they go looking:

- ~/.claude/history.jsonl · The prompts you actually typed, across every project.

- ~/.claude/plans/ · Plan documents, flat, one file per plan.

- ~/.claude/tasks/<session-uuid>/ · Task lists, one set per session.

- ~/.claude/paste-cache/ · Long pastes, filed by content hash.

### What the picker will not do

It resumes. It does not search. There is no built-in way to ask which session touched a given file, where an error was finally solved, or what was decided about an approach six weeks ago, and the list you are shown covers one directory in one tool.

So the honest summary is that Claude Code gives you a very good way to continue yesterday, and no way at all to find last month.

### Searching instead of scrolling

across every session, every tool

```
$ chat-recall search "why did we drop the pooler"
  ranked, with the session each hit came from

$ chat-recall show <session-id> --full
  the whole conversation, printed
```

With the MCP server registered, the assistant runs those queries itself mid-task rather than waiting to be asked. [The tool list is here](https://chatrecall.dev/mcp/).

### The clock you are reading against

Transcripts are kept for 30 days by default, set by `cleanupPeriodDays`. Anthropic documents the retention as being there to enable session resumption, which is exactly what it is good for and exactly why the older end of your history is being trimmed while you read this. [Where every tool stores its sessions](https://chatrecall.dev/guides/where-ai-coding-tools-store-sessions/) has the paths for the other five.

[Index what is already on disk](https://chatrecall.dev/app) [When the history is not there at all](https://chatrecall.dev/guides/claude-code-sessions-disappeared/)

## Claude Code session history disappeared: four reasons

> Four things make Claude Code sessions vanish from the picker, and only one deletes anything. Check the other three before you conclude the work is gone.

Source: https://chatrecall.dev/guides/claude-code-sessions-disappeared/
Published: 2026-09-24

### Check the cheap three first

Only the last of these removes data. Work through them in order, because the first three are a one-line check each.

### 1. You are in a different directory

The picker is scoped to the working directory you launched from. Sessions from a sibling repository, or from the same repository entered by a different path, are not in the list and never were. Go back to the directory the work happened in and run `claude --resume` there.

### 2. The directory was renamed or moved

Claude Code files sessions under the working directory with each slash turned into a dash:

the folder is named after the path

```
/home/user/code/example   ->  ~/.claude/projects/-home-user-code-example/
/home/user/work/example   ->  ~/.claude/projects/-home-user-work-example/
```

Move or rename the repository and new sessions land in a new folder, while every old one stays filed under the old name. Nothing is lost. List `~/.claude/projects/` and the old folder is usually sitting right there.

### 3. A second profile has its own tree

`CLAUDE_CONFIG_DIR` does not add a setting; it relocates the entire config root. Work done with it set to `~/.claude-work` writes to `~/.claude-work/projects/`, and anything reading `~/.claude` sees none of it. If you run more than one profile, you have more than one history, and each is invisible to the other.

### 4. The 30-day sweep took it

This is the one that actually deletes. Transcripts are kept for 30 days by default, set by `cleanupPeriodDays`, and the sweep runs against the transcripts rather than the auto-memory directory, which is excluded. If the session is older than your retention window and the folder is correct, the file is gone from disk.

Raising `cleanupPeriodDays` changes the window from now on. It does not bring back anything already swept.

### Finding it without the picker

The picker is not the only way in. If the file still exists, grep will find it:

every profile, every project

```
$ ls ~/.claude*/projects/
  every project folder, including profiles you forgot about

$ grep -rl "the thing you remember saying" ~/.claude*/projects/
  filenames; the content is JSONL, so pipe a hit through jq
```

### The only fix that works before the fact

Three of the four causes above are about where you are looking. The fourth is a clock, and a clock cannot be argued with after it has run. An index reads the transcripts while they still exist and keeps what it read, so the 30-day window stops being the limit on how far back you can ask. It also spans the profiles and directories that the picker splits your history across. [How to view the history you do still have](https://chatrecall.dev/guides/claude-code-session-history-viewer/).

[Index it before the sweep does](https://chatrecall.dev/app) [Where every tool keeps its sessions](https://chatrecall.dev/guides/where-ai-coding-tools-store-sessions/)

## Cursor chat history: where it lives and how to read it

> Cursor keeps chat history in two different SQLite databases depending on whether you used the IDE or the CLI, and it has moved the IDE format three times.

Source: https://chatrecall.dev/guides/cursor-chat-history/
Published: 2026-09-24

### Two surfaces, two databases

- Cursor IDE (desktop) · `~/.config/Cursor/User/globalStorage/state.vscdb`. On macOS, under `~/Library/Application Support/Cursor/` instead.

- cursor-agent (CLI) · `~/.cursor/chats/<md5 of the working directory>/<chatId>/store.db`, one database per chat.

Note the capital C. On Linux, `~/.config/cursor` in lowercase is the CLI auth directory and contains no chats at all. Both directories exist, and looking in the wrong one is the most common reason people conclude their history is missing.

### The schema has moved three times

An install upgraded in place keeps its older rows, so all four of these are still out there. Verified against a live Cursor 3.17.8 install, in the order a reader should try them:

- composerHeaders table · Current, seen on 3.15.6 and later.

- composer.composerHeaders · An ItemTable key in the global database. Cursor 3.0.

- composer.composerData · An ItemTable key in each per-workspace database. Roughly 0.45 through 2.x.

- The pre-0.45 chatdata keys · Self-contained, and they encode the speaker differently: the bubble type is the string user or ai, where every later era uses the number 1 or 2.

The first three all keep message content the same way, as `composerData:<id>` and `bubbleId:<composerId>:<bubbleId>` rows in the global `cursorDiskKV` table. Only the index moved, which is why a query copied from a year-old blog post returns nothing on a current install and nobody can tell you why.

### Two rules before you open it

Both of these come from reported data loss, not from caution.

Open it read-only. Cursor keeps a live write-ahead log while it is running, and the forums carry cases of histories destroyed by an outside process writing to the database underneath it. Close Cursor, or open the file read-only, or copy it first.

Bound every read. One reported `state.vscdb` had grown to 30 GB of `bubbleId` and `agentKv` rows. An unbounded `SELECT` against that is not slow, it is an out-of-memory kill.

### Exporting a chat

read-only, on a copy

```
$ cp ~/.config/Cursor/User/globalStorage/state.vscdb /tmp/cursor-copy.db

$ sqlite3 -readonly /tmp/cursor-copy.db "SELECT composerId, createdAt
    FROM composerHeaders ORDER BY lastUpdatedAt DESC LIMIT 20;"
```

If that table does not exist, the install predates it and you are in era two or three above.

### Why tailing the file loses data

The CLI rewrites its transcript on every resume rather than appending to it. Measured on one chat, a five-line file came back as a nine-line file with the original terminator gone. Any tool that remembers a byte offset and reads forward from it silently loses the rewritten portion, which is why Cursor needs a full read every time while the JSONL tools can be read incrementally.

### Reading it alongside everything else

Both Cursor surfaces are one source: the CLI emits an agent id and the IDE a composer id, both UUIDs, so they share a namespace and land in one history with your other tools. `CHAT_RECALL_CURSOR_HOME` and `CHAT_RECALL_CURSOR_IDE_HOME` override the two paths for a non-standard install. [Using several tools without losing the thread](https://chatrecall.dev/guides/multiple-ai-coding-tools/) covers the rest of the set.

[Index your Cursor history](https://chatrecall.dev/app) [Every tool, every path](https://chatrecall.dev/guides/where-ai-coding-tools-store-sessions/)

## The three kinds of MCP memory server

> Knowledge-graph stores, note-takers and session indexes are three different products wearing one label. Which one you need depends on a single question.

Source: https://chatrecall.dev/guides/mcp-memory-servers-compared/
Published: 2026-08-25 · Updated: 2026-09-22

### One label, three different products

- Knowledge-graph stores · The assistant writes entities and relationships, then reads them back later. The reference `server-memory` tool is exactly this. Great for durable facts you state on purpose. Starts empty, and only ever holds what an agent chose to write down.

- Note-takers · The assistant writes a prose summary at the end of a session, then searches those summaries later. Cheaper than storing full transcripts, and better than nothing at all. But it loses exactly the wrong thing: it keeps the conclusion and drops the reasoning that led there.

- Session indexes · Something indexes the transcripts your tools were already writing to disk. Nothing has to be recorded on purpose, because the recording already happened. This is the category chat-recall belongs to.

### The question that separates them

What does it already know on day one?

A knowledge-graph store and a note-taker both start out empty. They only become useful after weeks of disciplined writing, which means their value depends on a habit you have to actually keep up. Most get installed once, then abandoned.

A session index starts out already knowing everything you've done. Your first search returns months of work, because the transcripts were sitting on disk long before the tool ever existed.

### The second question: whose sessions?

Almost every memory server only sees the tool it runs inside. Memory written from Claude Code is readable from Claude Code, full stop. Use a second AI coding tool and it keeps its own, separate memory. People usually describe this as their assistant "forgetting" the moment they switch.

Reading several tools' formats is unglamorous, fiddly work: different folders, different file shapes, different ideas of what even counts as a session. It's also the only way to get one memory that spans all of them.

### Where each one wins

- Use a knowledge-graph store when · You want a small, curated set of facts the assistant treats as ground truth: conventions, ownership, standing rules. You write each fact yourself, one at a time.

- Use a session index when · What you keep losing is what you already did: the approach you tried and dropped, the command that actually worked, a decision made six weeks ago in a completely different tool.

- Use both, honestly · They answer different questions, so there is no real conflict. chat-recall ships a knowledge graph right alongside the index for exactly this reason: facts you state on purpose and history you recover are not substitutes for each other.

- Use neither when · You work in a single tool, on a single repo, in sessions that wrap up the same day. `claude --continue` already covers that, for free. See [what it doesn't cover](https://chatrecall.dev/guides/claude-continue-alternative/).

### What to actually check before installing any of them

- Does it read what already exists, or does it start out empty?

- How many tools does it actually span? For most, the honest answer is one.

- Where does the data go? Transcripts often contain pasted credentials and client code, so ask what leaves the machine, and whether you can self-host it instead.

- Can the assistant search it on its own, or do you have to paste results back in yourself? A memory you have to operate by hand is really just a search box wearing a costume.

### The honest limits of the one we build

A session index can't recover reasoning that was never written down in the first place. Decide something in your head and type only the result, and no tool on earth gets that reasoning back. It's also only as good as the transcripts underneath it: a tool that writes nothing to disk can't be indexed, and the search is keyword-based, so it finds what was said rather than what you meant.

[Start free, no card](https://chatrecall.dev/app) [How it works](https://chatrecall.dev/how-it-works/)

## Compacting conversation: what Claude Code keeps and drops

> What auto-compact does to a long session, why the assistant starts contradicting itself afterwards, and how to get the lost detail back instead of retyping it.

Source: https://chatrecall.dev/guides/claude-code-compact-context-loss/
Published: 2026-08-25 · Updated: 2026-09-14

### What compaction actually is

Two things put the word in front of you. The status line counts down in `% until auto-compact`, and when it gets close Claude Code says so outright:

shortly before it fires

```
Autocompact will trigger soon, which discards older
messages. Use /compact now to control what gets kept.
```

A session that outgrows the model's context window can't just keep going as-is. Claude Code summarizes everything that came before and carries that summary forward instead of the full transcript. That's the right engineering trade-off: the alternative is refusing to continue at all.

The summary itself is good. It's also lossy, and it's lossy in one specific direction: it keeps the conclusions and drops the reasoning that produced them.

### How it shows up in practice

- It re-suggests something you already rejected · The rejection lived in the part that got summarized away. The reason it was rejected went with it, so the same idea comes back looking brand new.

- It forgets a constraint you stated once · "We can't use that library, licensing issue" survives as a fact for a while, then quietly stops. Constraints stated early in a long session are the most likely casualty.

- It loses the shape of a failed attempt · Six things you tried become "several approaches were attempted" — not enough detail to stop it from trying the seventh one identically.

- You can't tell it even happened · There's no marker anywhere in the answer. The assistant isn't aware it forgot anything, so it answers with the exact same confidence either way.

### What's actually still there

The full transcript is still sitting on your disk. Compaction appends one record to the session's `.jsonl` file and then keeps appending to that same file:

the boundary record

```
{"type":"system","subtype":"compact_boundary",
 "content":"Conversation compacted",
 "compactMetadata":{"trigger":"manual","preTokens":205229}}
```

In one session I pulled apart, that line sits at 1588 of 2257. Every message, tool call and rejected approach from the first 1587 lines is still there, in order, under `~/.claude/projects/<project>/<session>.jsonl`. The record straight after the boundary is a user message flagged `isCompactSummary`, and that summary is the whole of what the model now sees.

So the detail isn't gone. It's out of reach of the thing that needs it, and it has an expiry date: transcripts are deleted after `cleanupPeriodDays`, 30 by default.

### Putting it back within reach

An index over those transcripts turns "gone" into "one search away" — and, more usefully, lets the assistant do the searching itself instead of you trying to remember what to paste back in:

after a compact

```
> what did we decide about the connection pooler earlier?
  recall_search finds the exchange in the pre-compact transcript
  and quotes the reasoning, not just the conclusion
```

The same trick works across the boundary a compact creates. `recall_smart_resume` reads the whole session straight from disk, so it can report what was decided and what was left unfinished even when the model's own context no longer holds any of it.

### Compacting on purpose

The `trigger` field above is the difference between the two kinds. `manual` means you ran `/compact`; automatic means the token count ran it for you and chose what survived on its own. Running it yourself, early, is the only version where you get a say:

while you still have room

```
> /compact keep the three pooler configs we rejected
  and why each one failed. drop the file listings.
```

A [PreCompact hook](https://chatrecall.dev/guides/claude-code-compact-instructions/) supplies those instructions on every compaction, including the ones you did not ask for.

If you are starting something unrelated, [`/clear` is the better command](https://chatrecall.dev/guides/claude-code-clear-vs-compact/). It opens a new transcript and carries nothing forward, which beats paying window on a summary of work you have finished.

### The one habit that actually helps

Say decisions out loud, inside the session. "We're going with the pooler because prepared statements break in transaction mode" is a sentence that survives being indexed, and either of you can find it again later. The same decision left implicit in a diff isn't recoverable by anything, before or after a compact.

This is a real limit, not a marketing line: a classifier can only pick up reasoning that was actually written down somewhere. Nothing recovers what only ever existed in your head.

### What this doesn't fix

It doesn't stop compaction, and honestly it shouldn't — a session that never compacted would just fail outright instead. It also doesn't make the model's context window any bigger: recall works as a tool call, so the assistant fetches what it needs exactly when it needs it, and nothing gets spent on context it never actually uses.

[Start free, no card](https://chatrecall.dev/app) [What claude --continue does not do](https://chatrecall.dev/guides/claude-continue-alternative/)

## You pasted an API key into a coding session. Now what?

> Deleting the chat does not remove it. Where the key actually lives, how to find every session that contains one, and what to do in what order.

Source: https://chatrecall.dev/guides/api-key-pasted-into-ai-chat/
Published: 2026-08-25 · Updated: 2026-09-22

### Where it actually went

Your AI coding tool writes the session to disk as it goes. The paste is in that file the instant you hit send, and it stays there:

- `~/.claude/projects/<project>/<session>.jsonl`: Claude Code

- `~/.codex/`, `~/.gemini/antigravity-cli/`, `~/.config/opencode/`: the others, same idea, different shapes

Clearing the conversation in the UI doesn't touch those files. Neither does closing the terminal. If the directory gets backed up, or synced, or sits on a machine someone else can read, the key is now in all of those places too.

### What to do, in order

- 1. Rotate it · First, before anything else, no matter how confident you are that nobody saw it. Rotating is cheap; not rotating is a bet. Everything below is about finding the rest, not about whether to rotate this one.

- 2. Find the others · If you pasted a key once, you've almost certainly pasted one before. The real question isn't whether this key is exposed — it's how many are, and grepping for one string by hand won't answer that.

- 3. Decide about the files · Deleting a transcript removes the credential, but it takes the work with it. Usually the better call is to rotate the key and keep the history, once you know what's actually in it.

### Finding every single one

A grep for `sk-` finds one shape of one provider's keys and misses everything else: tokens that are just plain hex, credentials sitting in a pasted `.env` file, a connection string with the password baked right in. Scanning by pattern per provider is what actually catches all of it:

every tool, every session

```
> do I have any leaked secrets?
  recall_security_summary: distinct credentials, grouped,
  with which sessions each one appears in
```

chat-recall scans as it indexes rather than only when asked, so the answer is already waiting before you even think to ask. Findings are grouped by credential rather than by occurrence: one key pasted into nine sessions is one thing to rotate, not nine separate alerts.

### Redaction happens before upload, not after

Worth being precise here, because it's the part that would otherwise make things worse. The scan and the redaction both run on your own machine, inside the CLI, before anything gets sent anywhere. What reaches our server is already redacted. Self-hosting removes the question entirely: see [self-hosting](https://chatrecall.dev/self-hosting/).

### Not doing this again

Reference the variable, not the value. Say `$STRIPE_SECRET_KEY` instead, and the agent can reason about your config just fine without the actual secret ever entering the transcript. Nearly every "show me your config" exchange works exactly as well this way.

Worth putting in the project instructions your agent reads, so it becomes a standing rule instead of something you have to remember mid-debug, at the exact moment you're least likely to.

[Scan your history free](https://chatrecall.dev/app) [How it works](https://chatrecall.dev/how-it-works/)

## Using several AI coding tools without losing the thread

> A practical setup for working across several AI coding tools at once: what breaks when you switch tools, and how to keep one memory across all of them.

Source: https://chatrecall.dev/guides/multiple-ai-coding-tools/
Published: 2026-08-23 · Updated: 2026-09-22

### Why people end up with more than one

Each tool is genuinely better at something. One handles a long refactor without losing the thread. One is faster on a single, well-specified file. One is already installed on whatever machine you're ssh'd into right now. None of that is a reason to consolidate down to one — it's a reason to keep using all of them.

The real cost shows up somewhere else. Every one of them writes a complete transcript of your session to disk, in its own format, in its own folder, and none of them ever reads another's. So the decision you argued through on Tuesday in one tool is completely invisible on Wednesday in another.

### What you actually lose

Not the code — the code is safe in git. What goes missing is the part that was never committed in the first place:

- the approach you tried first, rejected, and the reason why

- the one command that finally worked, after six that didn't

- which of two libraries you picked, and what actually made the difference

- the half-finished thing you meant to circle back to

That material only ever exists in the transcript. It's also exactly the material you'd have to re-explain to a new tool from memory, badly.

### The setup

Index what's already sitting on disk, and register the MCP server in each tool's own config:

once, per machine

```
$ npx chat-recall init
  finds every tool you have installed and wires each one up
```

Nothing gets migrated and nothing gets converted. Every tool keeps writing exactly what it always wrote; the index just reads those files.

### What changes day to day

The search box matters less than who's actually holding it. The assistant gets one, and uses it inside the conversation while it works, on its own.

- Starting where you stopped · "Continue where we left off" resolves to the real prior session, including which files it touched and what it left unfinished, instead of some summary you had to write by hand.

- Asking across tools · "Have we hit this error before?" gets answered from every session in every tool, including the ones you've stopped using entirely.

- Trying a fourth tool · Its first run isn't day one anymore. It queries the same memory as the others, so trying it out actually tests the tool, not your patience for re-explaining the codebase.

- Not redoing work · A prompt hook warns you when the thing you're about to ask for has already been done somewhere you'd forgotten about.

### Two habits worth picking up

Say what you decided, out loud, in the session. A decision written as "we're going with the pooler because prepared statements break in transaction mode" is recoverable later. The same decision left implicit in a diff isn't. The classifier only picks up explicit phrasing, nothing else.

Reference credentials by variable name. Paste a key into a prompt and it's sitting in the transcript, on disk, for as long as that file exists, whether or not you delete the chat afterward. Say `$OPENAI_API_KEY` instead. Sessions do get scanned for credentials, and live ones get verified against the issuing service, but not leaking it in the first place is a lot cheaper than rotating it after.

### Where the data actually sits

On your own server, or on ours. Running it yourself is free and fully featured for one person, with no licence key and no telemetry. If the work falls under someone else's NDA, run it yourself — the self-hosted build is the whole product, not a trimmed-down version. See [self-hosting](https://chatrecall.dev/self-hosting/).

[Start free, no card](https://chatrecall.dev/app) [Switching tools](https://chatrecall.dev/switch-tools/)

## What claude --continue does not do

> claude --continue resumes one session, in one tool, in one directory. What to use when the thing you need is older than that, or was not in Claude Code at all.

Source: https://chatrecall.dev/guides/claude-continue-alternative/
Published: 2026-08-23 · Updated: 2026-09-22

### What the built-in already covers

`claude --continue` picks back up the most recent session in the current directory, and `claude --resume` lets you pick from a list instead. For "I closed the terminal an hour ago and want to keep going," that's the right tool, and nothing here improves on it.

### Where it stops working

- One directory · The list is scoped to wherever you're standing. Work done in a sibling repo, or in the same repo from a different path, never shows up.

- One tool · It knows nothing about the session you ran in Codex or OpenCode, because that transcript lives in a different format, in a different folder entirely.

- Resume, not search · You pick from a list of recent sessions. There's no way to ask which session touched a given file, where a particular error got solved, or what was decided about a design six weeks ago.

- You have to ask · Resuming only happens when you do it deliberately. The assistant can't check its own history mid-task, because it has no tool that lets it.

### What actually fills the gap

Nothing replaces the built-in — keep using it for the same-day, same-directory case. The gap it leaves is recall, and recall is fundamentally a search problem:

what --continue cannot answer

```
$ chat-recall search "why did we drop the pooler"
  every session, every tool, ranked

> what was I working on yesterday?
  the assistant answers from the index, across all of them
```

And once the MCP server is registered, the assistant runs those queries itself instead of waiting to be told to.

### The honest comparison

- Same session, same day, same directory · Use `claude --continue`. It's free and it's already sitting right there.

- Something from last month · Search. Scrolling through a list of recent sessions won't find it.

- Something you did in another tool · Search. The built-in can't see it at all, in any form.

- Letting the assistant check for itself · MCP. The agent queries the index directly instead of you pasting results back in.

[Start free, no card](https://chatrecall.dev/app) [How it works](https://chatrecall.dev/how-it-works/)

## Where every AI coding tool stores your sessions on disk

> Exact paths and formats for every AI coding tool chat-recall reads: and the retention period that quietly deletes them.

Source: https://chatrecall.dev/guides/where-ai-coding-tools-store-sessions/
Published: 2026-08-28 · Updated: 2026-09-22

### The six locations

These are the default paths. Each one can be overridden, and the environment variable that does it is in the last column, since a machine running two profiles ends up with two of these trees instead of one.

- Tool · Where the transcript lives · Format · Override

- Claude Code · `~/.claude/projects/<project>/<uuid>.jsonl` · JSONL, one event per line · `CHAT_RECALL_CLAUDE_HOME`

- Codex · `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` · JSONL "rollouts", filed by date · `CHAT_RECALL_CODEX_HOME`

- OpenCode · `~/.local/share/opencode/opencode.db` · SQLite: tables `session` and `message` · `CHAT_RECALL_OPENCODE_DB`

- Antigravity · `~/.gemini/antigravity-cli/brain/<uuid>/.system_generated/logs/` · JSONL: read `transcript_full.jsonl`, not `transcript.jsonl` · `CHAT_RECALL_AGY_HOME`

- Cursor (CLI) · `~/.cursor/chats/<md5 of cwd>/<chatId>/store.db` · SQLite, one file per chat · `CHAT_RECALL_CURSOR_HOME`

- Cursor (desktop) · `~/.config/Cursor/User/globalStorage/state.vscdb` · SQLite. On macOS: `~/Library/Application Support/Cursor/` · `CHAT_RECALL_CURSOR_IDE_HOME`

### Four things that catch people out

- Claude Code deletes them after 30 days · Anthropic's own documentation is explicit about it: transcripts are kept "for 30 days by default to enable session resumption," and `cleanupPeriodDays` sets that period. So the archive you assume you have is really a rolling window, and the oldest end of it is being trimmed away while you read this.

- They're stored in plaintext · Also Anthropic's own wording. Anything you pasted is readable by anything that can read your home directory at all: a backup agent, a sync client, another account on a shared machine.

- A second profile means a second tree · `CLAUDE_CONFIG_DIR` creates a whole parallel root, so work done under `~/.claude-work` is invisible to anything only looking at `~/.claude`. The same holds for a second OpenCode database.

- Two of them aren't append-only · Cursor's CLI rewrites its own transcript every time you resume a chat, and both Cursor surfaces and OpenCode keep their data in SQLite. A simple tail-the-file approach works fine for the JSONL tools and quietly loses data on these two.

### What else Claude Code keeps besides the transcript

- `~/.claude/history.jsonl`: the prompts you actually typed

- `~/.claude/plans/`: plan documents, flat, one file per plan

- `~/.claude/todos/` and `~/.claude/tasks/<session-uuid>/`: task lists, one set per session

- `~/.claude/paste-cache/`: long pastes, filed away by content hash

- `~/.claude/projects/<project>/memory/`: auto memory, which is [excluded from the 30-day sweep](https://chatrecall.dev/guides/claude-code-auto-memory-limits/)

### Grepping them by hand

For one string in one tool, this is honestly all you need:

one tool, one string

```
$ grep -rl "pgbouncer" ~/.claude/projects/
  gives you filenames; the content is JSONL, so reading it
  means piping each hit through jq
```

It stops being enough by the third tool, because two of the six store data in SQLite and one of those rewrites itself constantly. That's the actual work an index does: read all six formats, normalize them into one shape, and let the assistant query it directly. See [how it works](https://chatrecall.dev/how-it-works/).

### If you'd rather they weren't there at all

Deleting a transcript wipes out the work along with the credential, which is usually the wrong trade: [rotate first, then decide](https://chatrecall.dev/guides/api-key-pasted-into-ai-chat/). If a whole project must never be read by anything, exclude it at the source instead of cleaning up after the fact:

excluded before it is read

```
$ chat-recall exclude project ~/work/client-project
$ chat-recall exclude tool cursor
```

[Index them free](https://chatrecall.dev/app) [What leaves your machine](https://chatrecall.dev/security/)

## Does Claude Code remember previous sessions?

> Partly, and the part it forgets is the expensive one. What CLAUDE.md, auto memory and --continue each carry across, and what none of them carry.

Source: https://chatrecall.dev/guides/does-claude-code-remember-previous-sessions/
Published: 2026-08-28

### The three things that do carry across

- CLAUDE.md · Instructions you write yourself, loaded at the start of every session. Great for standing rules: build commands, conventions, architecture. It's what you've decided should always be true, not a record of anything that happened.

- Auto memory · Notes Claude writes on its own, per repository, on by default. It captures your preferences and corrections. The index file loads every session; the detail files only load when Claude actually reaches for them.

- --continue and --resume · Reopens a recent session in the current directory. For "I closed the terminal an hour ago," this is the right tool, and nothing improves on it.

So the answer is yes, partly. A lot of what's written on this still says no — that stopped being true a while ago.

### What none of them carry

All three keep the conclusion. None of them keeps the work.

Picture a Tuesday afternoon spent wrestling a connection pooler. You try four configurations, three fail for different reasons, and the fourth finally works because transaction pooling rewrites the session and breaks named prepared statements. Six weeks later:

- CLAUDE.md only has it if you stopped mid-debug to write it down, which you didn't, because you were busy debugging.

- Auto memory might hold "prefers the direct connection": a preference, not a reason. It deliberately skips anything it judges derivable from the codebase.

- --continue can't reach it at all. The session isn't recent, and might not even be in this directory.

The three failed attempts are the genuinely valuable part, and they're exactly the part with no mechanism to keep them.

### Four more limits worth knowing

- One tool · All of it belongs to Claude Code. A session you ran in another AI coding tool is invisible to every one of these mechanisms, Claude included.

- One machine · Auto memory is machine-local by design. Your laptop and your desktop each build up their own, separate copy.

- Thirty days · Transcripts get deleted after `cleanupPeriodDays`, 30 by default. The raw record of what happened has an expiry date on it; auto memory is excluded from that sweep, but the transcripts aren't.

- You have to ask · Resuming only happens on purpose. Mid-task, Claude can't go check whether it's solved this exact problem before, because nothing gives it a way to look.

### Closing the gap

The transcripts are already sitting on disk. Indexing them turns that record into something searchable, and registering the index as an MCP server is what lets the assistant search it without you asking:

mid-conversation, unprompted

```
> have we hit this pooler error before?
  recall_search returns the Tuesday session, including the
  three attempts that failed and why
```

Use it alongside the built-ins, not instead of them. CLAUDE.md is still the right place for standing rules, and `--continue` is still the right way to reopen this morning's session. See [what --continue doesn't cover](https://chatrecall.dev/guides/claude-continue-alternative/).

## Claude Code has auto memory. Where it stops.

> Auto memory writes notes about your preferences per repository, on one machine. What it is good at, the four boundaries it does not cross, and what to pair it with.

Source: https://chatrecall.dev/guides/claude-code-auto-memory-limits/
Published: 2026-08-28 · Updated: 2026-09-22

### What it actually does

As Claude works, it saves notes to itself, filed under four kinds: your role and preferences, corrections you've given it, ongoing project context, and pointers to things outside the repository. They live in `~/.claude/projects/<project>/memory/` as plain markdown — a `MEMORY.md` index plus one file per topic. The index loads at the start of every session; the topic files only get read on demand.

Two design choices are worth calling out, because both are correct and both are limits at the same time. Claude deliberately skips anything it can derive from the codebase, and it skips anything CLAUDE.md already covers. So auto memory is, by design, the leftover: whatever's true about working with you that's written down nowhere else.

### The four boundaries

- One repository · Each project gets its own directory, keyed to the git repository. Worktrees of the same repo share it; two different repositories never do. A convention you set up in one service doesn't follow you to the next.

- One machine · The documentation is explicit that files aren't shared across machines or cloud environments. Your laptop and your desktop build up two different memories of the same person.

- One tool · It belongs to Claude Code, and only Claude Code. Nothing you did in another AI coding tool ever makes it in, and nothing in it is visible to them either.

- What Claude chose to write · Claude doesn't save something every single session; it judges what's likely to be useful later. That judgment is usually good, but it's still a filter applied at write time, before anyone actually knows what will be needed.

### The boundary that costs you the most

The last one deserves its own paragraph, because it's really the difference between two kinds of product, not just a rough edge on one.

Auto memory is a written record. A session index is a recovered one. A note says "prefers the direct connection." The transcript holds the entire afternoon that produced it: the four configurations, the three failures, and the exact sentence explaining that transaction pooling rewrites the session so named prepared statements resolve against the wrong backend. No note-taking policy recovers that later, because at the time it was written, it was just debugging.

There's also a hard clock running on it. Anthropic's documentation says the memory directory is excluded from the retention sweep, but the transcripts themselves are kept for 30 days by default, set by `cleanupPeriodDays`. So the notes stick around, and the evidence behind them quietly expires.

### What to pair it with

If you are weighing this against an MCP memory server, the three kinds of those are [compared here](https://chatrecall.dev/guides/mcp-memory-servers-compared/) — they are not all the same product.

- Keep auto memory on · It costs nothing, and it fixes the "I told you last week" complaint within a single repository. Nothing here is an argument for turning it off.

- Keep CLAUDE.md for rules · Standing rules belong somewhere deliberate and reviewable, in version control where your whole team can see them. Don't wait around for Claude to notice a rule on its own.

- Index the transcripts · For the part with no mechanism at all: what was tried, what failed, and why. It works across all six tools and every machine you use, because it reads what the tools already wrote.

- State decisions out loud · "We're going with the direct connection because prepared statements break in transaction mode" is a sentence every one of these mechanisms can hold onto. The same decision left implicit in a diff is recoverable by none of them.

### Checking what it already has

in a session

```
> /memory
  browse the files, toggle auto memory, open the folder
```

It's plain markdown, so go read it, edit it, delete whatever's wrong. A memory you can't audit is a liability — this one, you actually can.

[Index your sessions free](https://chatrecall.dev/app) [What each mechanism keeps](https://chatrecall.dev/guides/does-claude-code-remember-previous-sessions/)

## Context left until auto-compact: what the number counts

> The percentage in the status line, what makes it fall, how to move the threshold, and what actually happens to your conversation when it reaches zero.

Source: https://chatrecall.dev/guides/context-left-until-auto-compact/
Published: 2026-09-14

### What the number counts

The status line shows `% until auto-compact`, and some setups show `% context used` instead. Both describe the same thing from opposite ends: how much of the model's context window this session has filled, and how much room is left before Claude Code summarizes everything so far and carries on from the summary.

Below a threshold it changes tone and says `Context low` with the remaining percentage. Shortly before it fires you get the real warning:

the warning worth reading

```
Autocompact will trigger soon, which discards older
messages. Use /compact now to control what gets kept.
```

That sentence is doing more work than it looks like. Compaction happens either way; running it yourself is the only version where you choose what survives.

### Why it falls faster than you expect

Every session starts with a fixed cost before you type anything: the system prompt, every tool definition from every MCP server you have registered, and the CLAUDE.md files for the project. Add four MCP servers with a few dozen tools between them and a meaningful slice of the window is spent at startup, on every single session.

After that, the things that move the number fastest are rarely your messages. Reading a large file puts the whole file in context. A test run that fails puts the whole output there. A search across a big repository can cost more than an hour of conversation.

### Moving the threshold

- `/autocompact` · Opens the window picker inside a session. It reports the current window and what set it, so you can see when something else is overriding your choice.

- `--autocompact <auto|tokens>` · The same setting as a launch flag. `auto` lets Claude Code size the window to the model; a number pins it.

- `CLAUDE_CODE_AUTO_COMPACT_WINDOW` · The environment variable. It wins over the setting, and Claude Code tells you so when you try to change the window while it is set.

- `autoCompactWindow` · The settings key, for when you want the choice to persist rather than live in one shell.

### Turning it off is the expensive option

You can. `DISABLE_AUTO_COMPACT` in the environment, or `autoCompactEnabled` in settings, and the status line switches to `auto-compact is off`. Claude Code is direct about the consequence: without it you hit the context limit and lose the conversation instead, and your only remaining move is running `/compact` by hand before you get there.

There is a related setting that does not turn anything off — Claude Code can precompute the summary in the background before it is needed, which only applies while auto-compact is on. The pause you notice at the boundary is what that removes.

### What reaching zero actually does

It writes one record into your transcript file and keeps going in the same session:

from a real transcript

```
{"type":"system","subtype":"compact_boundary",
 "content":"Conversation compacted",
 "compactMetadata":{"trigger":"manual","preTokens":205229}}
```

Everything before that line is still in the file. In the session I pulled that from, the boundary sits at line 1588 of 2257 — so 1587 records of conversation are on disk, in order, after the model stopped being able to see them. The next record is a user message flagged `isCompactSummary`, and that summary is what the model reads from then on.

So the percentage is not counting down to deletion. It counts down to the point where the detail moves out of the conversation and into a file, where finding it again takes a search.

### Three things that buy you room

- Start a new session for a new task. The fixed startup cost is paid either way, and a fresh window beats a summarized one for work that shares nothing with what came before.

- Unregister MCP servers you are not using in this repo. Their tool definitions are in the prefix of every session whether you call them or not.

- Run `/compact` yourself, with instructions, at a point you choose instead of one the token count chooses. [What to put in those instructions](https://chatrecall.dev/guides/claude-code-compact-instructions/).

[Index your sessions free](https://chatrecall.dev/app) [What a compact costs you](https://chatrecall.dev/guides/claude-code-compact-context-loss/)

## /clear vs /compact in Claude Code

> One summarizes the conversation and keeps going. The other starts a fresh one. What each does to the transcript on disk, and which to reach for.

Source: https://chatrecall.dev/guides/claude-code-clear-vs-compact/
Published: 2026-09-14

### The short answer

- `/compact` · Summarizes the conversation so far and continues in the same session. The assistant still knows roughly what you have been doing. Reach for it mid-task.

- `/clear` · Starts fresh. Nothing carries over, which is the point when you have finished one thing and are starting another. Claude Code's own tip is to use it when switching topics.

Same task, keep going: compact. Different task: clear. That covers most days, and two cases below break it.

### What each one does to the file on disk

This is the part neither help string mentions, and it is the part that matters a week later. Both commands are recorded, and neither deletes anything.

`/compact` stays in the same file. It appends a boundary record and carries on appending after it:

same session, same .jsonl

```
{"type":"system","subtype":"compact_boundary",
 "content":"Conversation compacted",
 "compactMetadata":{"trigger":"manual","preTokens":205229}}
```

In a session I checked, that boundary sat at line 1588 of a 2257-line file: 1587 records before it, all still there, all still in order. The record immediately after it is a user message flagged `isCompactSummary`, which is the summary the model reads from then on. Everything the summary dropped is sitting a thousand lines above it.

`/clear` opens a new file. The old session's `.jsonl` is closed and left exactly as it is, and a new one starts with a new session id. In the new file, the first thing recorded is the clear itself:

line 4 of a brand new .jsonl

```
<command-name>/clear</command-name>
```

So neither command loses your history in the sense people worry about. What you lose is reach: after a compact the model holds a summary, and after a clear it holds nothing at all.

### Which one to reach for

- Long refactor, context filling up · `/compact`. You want the thread. Give it instructions while you are there so it keeps the right half.

- Finished the bug, starting a feature · `/clear`. A summary of the bug is dead weight on the feature, and it costs you window on every turn that follows.

- The session has gone wrong · `/clear`. Compaction would carry the confusion forward in condensed form. This is the case where the rule of thumb gets it wrong.

- You are about to hit the limit · `/compact`, now, with instructions. Auto-compact fires on its own shortly after and picks for you.

### Turning them off

One environment variable covers both, and it is worth knowing which. `DISABLE_AUTO_COMPACT` stops the automatic one and leaves you the manual command. `DISABLE_COMPACT` disables manual `/compact` as well, so a session that fills up has nowhere to go.

### Getting back what /clear left behind

The previous transcript is a complete file on your disk, and the one thing that cannot read it is the assistant that wrote it. An index over those files closes that:

in the session after the clear

```
> what did we settle on for the pooler yesterday?
  recall_search reads the earlier transcript and quotes
  the exchange, including the two options that were dropped
```

It works the same across a compact boundary, which is the harder case: the file holds both halves, so the reasoning the summary discarded is still retrievable even though the model can no longer see it.

Claude Code keeps transcripts for 30 days by default, set by `cleanupPeriodDays`. After that the file is gone and no search helps.

[Start free, no card](https://chatrecall.dev/app) [What a compact costs you](https://chatrecall.dev/guides/claude-code-compact-context-loss/)

## Compact instructions: tell /compact what to keep

> Compaction decides what survives unless you decide for it. Passing instructions to /compact, and the PreCompact hook that supplies them every time.

Source: https://chatrecall.dev/guides/claude-code-compact-instructions/
Published: 2026-09-14

### The one-off version

`/compact` takes an argument, and the text you pass is added to the prompt that writes the summary, under a heading called Compact Instructions. The same thing is available to the SDK, where the session compact call takes an instructions string or nothing at all.

before the window fills

```
> /compact keep the three pooler configs we rejected
  and why each one failed. drop the file listings.
```

Be specific about what to drop as well as what to keep. A summary has a budget, and "keep everything about X" without "drop Y" spends that budget on the same material it would have kept anyway.

### What is worth naming

- Rejected approaches, with reasons · The first casualty every time. Six attempts become "several approaches were attempted", which is not enough detail to stop the seventh from repeating the second.

- Constraints stated once, early · A licensing rule or a version pin you mentioned in the first ten minutes is the most likely thing to quietly stop being true.

- The exact failing command · Summaries paraphrase commands into descriptions of commands, and a paraphrased command cannot be re-run.

- What to drop · Directory listings, file contents you have already edited, and long test output. Naming them is what makes room for the rest.

### The hook, for when you forget

You will forget, because compaction arrives during the part of a session where you are concentrating on something else. The `PreCompact` hook runs before every compaction and supplies the instructions for you. Its contract is short:

- Input · JSON on stdin with the compaction details.

- Exit 0 · Whatever the command printed to stdout is appended as custom compact instructions.

- Exit 2 · Compaction is blocked. Claude Code reports it and continues uncompacted.

- Any other exit · stderr goes to you, and compaction proceeds anyway.

So a hook that echoes four lines of standing instructions gives every compaction in every session the same floor, whether you triggered it or the token count did. There is a matching `PostCompact` hook that receives the compaction details and the summary, which is the place to record that a boundary happened.

Exit 2 comes with a warning. Blocking compaction does not create context; it leaves a session running against a window it has already outgrown, and the failure that follows is worse than the summary you avoided.

### What instructions cannot do

They shape a summary. They do not make one lossless, and no wording gets a long afternoon of debugging through a summary intact — the budget is the budget. They also cannot preserve something nobody wrote down: reasoning you did in your head and typed only the result of is not in the transcript, so it is not in the summary either.

The backstop for both is that the full transcript never went anywhere. Compaction appends a `compact_boundary` record to the session file and keeps writing to the same file, so the material the summary could not fit is still on disk, in order, a few hundred lines up.

after the boundary

```
> what were the three pooler configs we rejected?
  recall_search reads past the boundary and quotes the
  original exchange, not the summary of it
```

Write instructions for the summary, and keep an index for everything the summary had to leave out. The two solve different halves of the same problem.

[Index your sessions free](https://chatrecall.dev/app) [When compaction fires](https://chatrecall.dev/guides/context-left-until-auto-compact/)