# Moving to Linetta 1.0

Linetta 1.0 removes the built-in AI companion. The app is a writing tool now; AI
collaboration happens in a client you already run, connected over MCP.

If you never used the companion, nothing about your writing changes and you can
skip this page.

## What happened to your conversations

They are still there. Linetta does not drop the table.

Before or after upgrading, open **Settings → Backup → Export companion record**.
It writes one markdown file containing every project's transcript and the facts
the companion was told to remember, readable without Linetta installed. The row
only appears if your library actually holds a transcript.

Remembered facts were never in the database — they live in a per-project
`memory/experiences.jsonl` file, and an agent connected over MCP records and
recalls them the same way the companion did.

**Facts remembered before 1.0 needed rescuing, and Linetta now does it for
you.** 1.0 moved where that file is looked for — it was
`<app data>/companion/<project id>/memory/`, and it is now
`<app data>/<project id>/memory/` — but nothing moved the file, so for a while
an agent no longer recalled what the companion had remembered. Nothing was ever
deleted.

Since 1.2, Linetta moves those directories up one level when it starts, and
removes the `companion` folder once it is empty. There is nothing to click:
open the app and the facts are back where an agent reads them
([#114](https://github.com/devlikebear/linetta/issues/114)).

It moves a folder only when that folder really is memory: a directory holding
`memory/experiences.jsonl` as an ordinary file, with no symlink anywhere on the
way to it. Everything else it leaves exactly as it found it, and nothing in
`companion/` is ever changed or deleted.

Here is every case where it declines, and what you should do about each:

- **The project already has memories in the new place.** If both
  `<app data>/companion/<project id>/` and `<app data>/<project id>/` exist,
  Linetta touches neither — merging two `experiences.jsonl` files is not
  something it will do behind your back. *What to do:* nothing, unless you want
  the older facts back. The file is one JSON object per line, so you can append
  the old file's lines to the new one yourself, then delete the old folder.
- **The folder is not project memory.** Anything under `companion/` without
  `memory/experiences.jsonl` inside it stays where it is — and so does a stray
  file rather than a folder, which on macOS is usually the hidden `.DS_Store`
  the Finder writes as soon as you look inside. *What to do:* nothing. Linetta
  reads memory only from `<app data>/<project id>/memory/experiences.jsonl`, so
  moving something that is not that up one level would not make it readable —
  it would only put an unrecognised folder in a directory Linetta keeps its own
  files in. Delete it or leave it, as you prefer.
- **The folder is named for something else Linetta keeps.** `backups`, `codex`,
  `skills`, `folder-sync-staging`, `library.db`, `settings.json`, `mcp.json`
  and `companion` itself are refused by name, so a hand-made folder cannot be
  moved on top of one of them. Project ids are uuids, so a real project is
  never refused this way. *What to do:* nothing; rename it first if it really
  does hold a project's memory.
- **Something on the path is a symlink.** A linked folder, or a linked
  `memory/` inside a real one, is refused rather than followed: moving it would
  leave Linetta writing your memories to wherever the link points, outside its
  own data folder. *What to do:* if the link was deliberate, move the folder it
  points at to `<app data>/<project id>/` yourself and remove the link.
- **The move itself failed.** The likeliest cause is a rename across
  filesystems — `companion/` and `<app data>/` on different mounts — and Linetta
  does not fall back to copying, because a half-finished copy is worse than no
  copy. *What to do:* open the app again, which retries the whole pass; or move
  `<app data>/companion/<project id>/` up to `<app data>/<project id>/`
  yourself, which is the same move by hand.

The `companion` folder is removed once it is empty, so it is normally gone
after the first launch. **A `companion/` folder still there does not mean your
memories were left behind** — on macOS a single hidden `.DS_Store` is enough to
keep it, with every project folder already moved out from under it. Open it and
look: if it holds no `<project id>/` folders, everything moved and you can
delete what is left.

## What happened to your API keys, and what changes in 1.2

They were untouched in 1.0: Linetta stopped reading them, but did not delete
credentials you own.

**In 1.2, the built-in agent reads them again** — but only for a provider you
explicitly consent to. Being left alone in 1.0 is not consent: each provider
needs its own yes, given again in **Settings → AI provider**, and Linetta
refuses to build a request to any provider until that box is ticked. A key
sitting untouched in your OS credential store does not quietly start being
used.

If you would still rather have a credential gone than consent to it, here is
where to go and delete it:

| Platform | Where |
| --- | --- |
| macOS | Keychain Access → search `linetta` |
| Windows | Credential Manager → Windows Credentials → `linetta` entries |
| Linux | there is no secure secret store here, so a key you enter today cannot be saved and only the ChatGPT (Codex) sign-in works, storing its token in `<app data>/codex/auth.json`. **A key you entered before 3 June 2026 is a different matter**: those builds wrote it in plain text into `<app data>/settings.json`, under `providers`, and on Linux nothing has moved or cleared it since. **That key does nothing where it is** — Linetta reads provider keys only from the OS credential store, so a key left in `settings.json` is not used by the built-in agent, by MCP, or by anything else, no matter which boxes you tick. It is readable text and no more. Settings → AI provider now says so and offers to delete it for you; you can also open the file and delete the `api_key` value yourself |

On Linux `<app data>` is `$XDG_DATA_HOME/com.devlikebear.linetta`, or
`~/.local/share/com.devlikebear.linetta` when `XDG_DATA_HOME` is unset.

Your provider selection and model choices stay in `settings.json`, and in 1.2
they mean something again: it is what the built-in agent reads to decide which
provider to call.

## Setting up an agent instead

1. **Settings → Connect an external agent (MCP)**, tick the consent box, choose
   `read_only` or `full`, and press Enable.
2. Copy the `claude mcp add …` line the pane shows and run it. That is the whole
   setup for Claude Code.
3. For Claude Desktop, paste the `claude_desktop_config.json` snippet instead —
   it points at the bridge binary shipped inside the app.

Restrict access to one work with the project field if you want an agent nowhere
near the rest of your library.

## What is different in practice

**You keep the last word.** Every scene an agent writes is snapshotted first and
listed in the activity log, and `linetta_undo_last_change` reverses it. If you
are part way through editing a scene when an agent rewrites it, Linetta does not
replace your text — it tells you and waits.

**Summaries no longer come from a model.** A short scene is its own summary; a
longer one keeps its opening lines. An agent replaces either with a real summary
through `linetta_write_summary`, and Linetta will not overwrite what it wrote.

**Some things are gone.** The synopsis "rewrite" button needed a model, so it
went; the field is still typed into by hand or written by an agent. The Fact
Book no longer researches for you — you record a claim and its source, and
Linetta fetches the page. Web search settings are gone with the companion that
used them.

**References are read-only.** Material you attached before still reaches an
agent's story brief, but there is no longer a way to add more. A proper place to
manage them is planned.