Skip to content
ArcadiaLookoutDocs

Memory is what Lookout keeps between chats: your preferences, and facts about a project. A new chat starts with the list of what is remembered; longer details stay in their files until the agent reads them.

Memory has two scopes:

  • Everywhere: yours, in every project and every agent, on every machine signed in to your Lookout account.
  • A project's own: only in chats in that project, on every machine with a clone of its repository.
  • An agent's own: only in that agent's conversation. Whatever an agent saves or learns stays there, so one agent's role or notes never reach your coding chats or another agent.

An agent's Controls can keep Everywhere out of its conversation (Read Everywhere memory) and stop Lookout learning from it (Learn from its chat).

Each scope is a folder of Markdown files under ~/.lookout/, outside your project folders: a MEMORY.md list, plus a file for each memory with details.

A project's memory belongs to its git repository, not to the folder's path: every clone and worktree of one repository on a machine shares it, wherever it sits. A folder outside git keeps a memory of its own. When a project's memory first moves to its repository, two copies of it merge with nothing lost: each memory once, and of two versions of one topic the newer stays while the older goes to Forgotten (See and change what is remembered).

Save a memory

  • Ask the agent. Say "remember that the staging deploy needs the VPN". The agent saves it to the project. A save meant for Everywhere asks you first: a card in the chat offers Save everywhere, Save to this project and Don't save, and nothing is written until you pick. Settings › Memory › Save Everywhere memories changes who may save there: Ask me, Only me (an agent's save goes to the project instead), or Agents may save. An agent's forget of an Everywhere memory goes through the same setting: under Ask me a card shows the memory as it reads now and nothing is forgotten until you pick Forget everywhere (or Keep it), and under Only me the agent can't forget one.
  • Write a note. Start a message with # to note it for this project, or #! for Everywhere. The note is saved word for word, no turn starts, and the message says where it went. While Use memory is off, in Settings › Memory or in the project's settings, a note is not saved, and the reply says so.
  • Add it in Settings. Open Settings › Memory and click Add memory.
# The API tests need Docker running
#! I prefer small pull requests

A note is 3 to 400 characters. Lookout refuses a memory that looks like a password, key or token: save where the secret lives instead, such as the name of the variable that holds it.

Learn automatically

With Learn automatically on, Lookout reads a turn after it ends and keeps the preferences and project facts it picked up. It runs after a turn that did real work (at most once every 10 minutes in a chat), on the chat's own model. To have something kept at once, ask the chat to remember it, or write a # note. What it learns lands in that chat's own memory (the project's, or the agent's in an agent chat), never Everywhere, and Settings lists it as Learned. It can also forget a memory the turn proved wrong, or one you asked it to forget. A memory you wrote yourself is different: Lookout changes or forgets it only after a turn in which you spoke of it, such as "we moved off yarn, the yarn note is out of date". When the agent or Lookout rewrites a memory, Settings says so (edited by Lookout). Only what you type in Lookout is you speaking. A message one of your agents, another chat, or an app such as Claude Code sent (its row names the sender) never changes your own memories, nothing from it lands in Everywhere, and what Lookout keeps from it says who said it. A note such a sender saves is listed By the agent, not by you.

When a project's or an agent's memory gets crowded, Learn automatically also tidies it, at most every 6 hours: it merges memories that say the same thing and forgets task status, to-dos (runs or checks still owed) and what a newer memory contradicts. A memory that also holds a lasting fact, such as a decision or a measured result, is rewritten without those parts instead of forgotten. Each pass reads the memories changed or not read since the last one, oldest first, so a large memory is read whole over several passes; a merged memory keeps the date of the newest one it came from. When the list is within 10 of its 200 limit, a pass reads more of them, starting with those that have a close match, and brings it to about 180. It only merges memories about one subject, and forgets ones whose dates have passed. It may also forget a memory whose work has landed, when the pull request, commit or doc that memory names records it. The details a later task still needs and the pull request lacks move first, in up to three lines with the pull request number, into the memory about that feature; a memory with more stays. The same holds for any memory with measured numbers: it is forgotten only when the record it names holds them, or once they move into the memory about its subject. A record is a file Lookout can read at that moment, at the exact path the memory gives; a path that leads nowhere keeps the memory. A memory with a run still owed today or later stays. It never lumps different subjects together to shorten the list: when no more memories share a subject, the ones not saved, updated or read for the longest move out of the list until it is back at 180 (see Limits). A merge can carry a memory over word for word. A chat that started before a merge still lists the old memories, and reading one opens the memory it was merged into. What it takes is listed in Forgotten. It never tidies Everywhere, and never a memory you wrote yourself.

An agent may also edit a memory file directly (with a file tool or the shell). Lookout then does what a save would: the memory's date moves to that day, the text it replaced goes to Forgotten, Settings says the agent edited it, and a password, key or token written that way is taken back out.

Turn it off in Settings › Memory: the agent then saves a memory only when you ask. Use memory turns memory off altogether: chats read none and save none, and what is saved is kept. Both are on until you change them, and a project can set either one for its own chats (Memory per project).

Memory per project

A project's Project settings have the same two under Memory, each Default, On or Off. Default follows Settings › Memory, and On or Off holds for that project whatever Settings › Memory says.

  • Use memory off: the project's chats read no memories, neither the project's nor Everywhere, and save none: the agent is told memory is off there (an open chat, that the memories it was shown no longer apply), a save it tries anyway is refused, and a # note is not saved. What was remembered stays, and turning it on again brings it back, in open chats at their next message.
  • Learn automatically off: chats read memory as usual, the agent saves a memory only when you ask it to, and Lookout learns nothing from the project's turns. It waits on Use memory.

Scratch starts with Use memory off, on a new Mac and on one that had Scratch before. Turn it on like any project's. A chat an agent starts in a project follows that project's settings; an agent's own conversation and memory follow the agent's Controls. Under its switches, Settings › Memory lists the projects that differ, and Set to Default puts one back on Default: for Scratch, that turns its memory on while Use memory is on there.

See and change what is remembered

  1. Open Settings › Memory (⌘,).
  2. Pick whose memory in the scope menu: Everywhere, a project, or an agent under Agents. The page opens on the project or agent of the chat in view.
  3. Search, show only what was written By you, By the agent or Learned, and sort.
  4. Click a memory to edit it in a dialog, change where it Applies, see which chat it came from and open its file. Add memory opens the same dialog, and the trash beside a memory forgets it. To share an agent's memory everywhere, open it in that agent's scope and pick Everywhere. An Everywhere memory an agent's chat wrote offers Only with that agent's name, which moves it to that agent's own memory.

A memory forgotten in any way (by you, by the agent, or by Learn automatically) is kept for 30 days: Forgotten lists it with who forgot it and when, and Restore puts it back where it was. A memory that was rewritten keeps its earlier version there too, listed as replaced: Restore swaps the two, and restoring again swaps them back.

Open chats learn of your edits and forgets at their next message; what other chats save or Learn automatically changes reaches a chat when it starts. The eye beside the search, See what’s sent, shows the exact text a new chat starts with; a memory past what a chat is shown reads Not sent. The folder button opens the scope's folder.

On every machine

Your Everywhere memories are the same on each of your machines: the Mac, and each server you added to your Lookout account, including one that runs your agents. A memory saved or forgotten on one reaches the others within a couple of minutes, without a click, and opening Everywhere in Settings › Memory brings it up to date at once. A memory forgotten on another machine is in Forgotten here too, so it can be restored. They sync through your account's vault, as your provider sign-ins and connectors do.

Each memory keeps who wrote it, so one an agent wrote says Saved by with the agent's name on every machine that knows the agent.

When the same Everywhere memory changed on two machines before either heard of the other, the page says so above the list, and each machine keeps its own until you pick: Keep this machine’s sends this one to the others, Use the other machine’s takes theirs. The rest of your memories keep syncing meanwhile.

A project's memory follows its repository to each of your machines too: a chat on the Mac and a chat on a server in clones of one repository read and add to the same project memory, even while the other machine is off. It syncs every couple of minutes, or at once when you open Settings › Memory. When both machines changed the same memory before either heard of the other, the newer version stays on both and the older one goes to Forgotten on the machine that met both, so nothing is lost and nothing waits for you. A forget on one machine reaches the others, in their Forgotten too. A memory one machine moved out of a full list moves out on the others too, into their own retired/, and once an agent on any machine opens or saves it again it is back in the list on every machine. Thirty days after it moved out, the shared copy lets go of it so the shared copy never fills up; each machine keeps it in its own retired/, and it still comes back everywhere when opened or saved. A machine that was off for more than those 30 days may hold a memory another machine moved out meanwhile in Forgotten for 30 days instead; the machine that moved it out keeps it. When some memories can't be shared (the shared copy is full, or one looks like a password or key), the sync status names them and says why, instead of saying it is up to date. A machine that hasn't updated to a build that knows this yet leaves that project's memory as it is, and catches up once it updates. Your account keeps each project's memory sealed: it can't read it or tell which repository it belongs to. A project memory too large to share (over 1.5 MB, far past what a project holds day to day) stays on its machine until you forget some of it. A folder outside git, and an agent's own memory, stay on their machine.

Export and import

The export button (Export memories) saves a .zip of memory folders: the project or agent in view, Everywhere, or all memories, each agent's own included. As git repositories makes each folder a repository ready to push. Importing an export of all memories puts each agent's memory back into that agent only, never Everywhere or a project.

The import button (Import memories) adds memories to the scope in view:

  • Import a folder: any folder with a MEMORY.md, such as one Lookout exported or another agent's memory folder.
  • Import a .zip: a memory export.

A memory that is already there is skipped, and the result says what came in and what was left out.

Limits

  • A topic name is up to 120 characters, its description up to 150, and its file up to 25,000 bytes including frontmatter. SaveMemory refuses an oversized record with its size and the limit before writing, leaving an existing memory unchanged. Shorten it and save again; descriptions are not cut to fit.
  • A scope's list holds up to 200 memories in 48 KB, and up to 1 MB with details. The page shows how full it is. When Everywhere is full, new memories are refused until you forget some. When a project's or an agent's list is full, a new memory moves the ones not saved, updated or read for the longest out of the list, and the agent is told which. One used in the last three days, and one you wrote, stays. What moves out is kept in the memory folder's retired/ folder, listed in its RETIRED.md, and each chat's memory says where that list is. It goes back into the list as soon as an agent opens its file or saves it again.
  • A new chat is sent each list, newest first, up to 48 KB. Older memories past that, such as after a hand edit of MEMORY.md, show Not sent: the agent reaches them only by opening the file.
  • Rules: The instruction files a chat reads from each of its folders, how an edit reaches a running chat, and the ignore files that keep the agent out of paths.
  • Agents: Named agents with their own folder, memory and instructions, teams that message each other, routines on a schedule, and chats an agent starts.
  • Settings: Settings in the Mac app page by page: what each setting does, and its default.