Project memory

Project memory keeps a memory of each project: the decisions, conventions and pitfalls its agents have learned. Claude and Codex sessions in that project read it with the connecto memory command, and add to it as they work.

Memory is off by default, for each project. Turn it on for the projects where it helps.

What it is

Turn it on

  1. Open the project's settings: the gear on its row in the sidebar, or right-click the project and choose Project settings….
  2. Open the Project Memory tab and tick Keep a memory for this project.
  3. Choose how it starts:
    • Build the palace from the current project (recommended) opens Activity and starts the initial build. "Palace" is the name Connecto gives to a project's whole memory.
    • Start empty lets the memory fill as you work. You can build it from the project later, in Activity.
    • Cancel leaves memory off.

Untick the box to stop capture and both cycles. The data is kept. Terminals launched while memory is on are told about it in their launch text.

The initial build

For a project that already has code and history, the initial build reads what is there and writes the first version of the memory. It uses the same model as the dream cycle.

Before it starts, you choose what it reads. Exclude takes paths or globs, comma separated, that are never read. Documentation and instructions, manifests, component structure, relevant code, test configuration, git state and local changes, recent history and Connecto conversations are all on by default. You can also set:

SettingDefaultMeaning
History90 daysDays of git history and conversations.
Input limit2,000,000 charactersCharacters read in total. At least 12,000.
Time limit60 minutesWhen the limit is reached, the build publishes what it has analysed and marks the rest as not analysed.

Preview the plan shows, for each kind of source, what would be read and what is excluded, with about how many characters and model runs. It gives no cost estimate.

What is never read

These are skipped whatever you choose:

The exclusions apply to file contents. Other text, such as documentation or a commit message, can still mention an excluded path.

How git is used

Connecto checks the repository by reading its files itself. It uses git only when nothing in the repository's setup could make git run a program or read somewhere else, such as Git LFS filters, hooks, an include or an initialised submodule. When git is not used, the build lists files by walking the folders, has no history or local changes, and says why under GIT.

Your system git configuration is never read. Git runs against a private folder under Connecto's data folder, on a copy of the index, with hooks and filters switched off.

What the build means

A file's text, code included, shows what is written down. It does not prove a fact. A decision read from a document becomes accepted only when the document is a decision record, such as an ADR or a file named adr-, decision- or rfc-. Source coverage, in Activity, lists what was analysed, excluded and still remaining. A finished build is not complete knowledge of the project.

While it runs, your terminals keep feeding the queue. Cancel the build stops it, and Resume continues from the last checkpoint. If you close the app, the build resumes at the next start.

A second build on a memory that already has content reconciles with the project. It adds and completes. It does not reset, merge or archive what is there, and it keeps the text and standing of memories you accepted.

How memories are added and tidied

There are two cycles. You set each one under Settings, with its own provider, model and effort.

The development cycle

While you work, a model reads new events in small batches and writes short notes, each with its sources. A note can be read at once.

SettingDefaultMeaning
Grouping window3600 secondsTime after the first event before a batch runs. Zero runs at once. A proposal or flag starts the batch at once.
Runs per hour, at most20Beyond it, the queue waits.
Input limit60,000 charactersPer run. A larger batch is split, never cut.
Attempts3Before a batch counts as failed. Retries wait 30 seconds, then twice as long each time, up to 30 minutes.

The default model is Claude haiku at low effort.

The dream cycle

At the time you choose, a model consolidates notes and evidence into memories. Connecto checks every change the model proposes, and publishes the result as one version. You can undo a version.

SettingDefaultMeaning
DaysMonday to FridayWith no day chosen, it never runs on schedule. Dream now still works.
Time02:30Local time.
Time limit30 minutesFrom the start of the dream to its publication.
Input limit200,000 charactersPer run. More is split by room. At least 5,000.
Minimum new items1Events or notes since the last dream. With fewer, that date counts as done, with no run.

The default model is Claude sonnet at medium effort. A scheduled dream runs at most once per date. A dream that fails still counts as that date's run.

Undo, on a version in Activity, restores what that version changed, as a new version. Notes that arrived later are not touched. Agents cannot undo a version.

What a memory says

Each memory shows three separate things. None is derived from another.

Status says how reliable it is:

StatusMeaning
candidatoRecorded with its sources, not yet independently confirmed.
verificatoAt least one independent confirmation.
da_verificareSomething it rests on changed, or the evidence was not enough. It needs checking. It is not false.
superatoReplaced by another memory.
conflittoSources disagree, and both stay visible.

Freshness says how recent it is: when it was last confirmed, whether a file it is anchored to changed, and how many open notes it has. A changed file does not make a memory false.

Standing says what the memory claims. Each kind has its own steps, weakest first:

KindStandings, weakest first
Decision, conventionproposed, accepted, discarded
Workplanned, in progress, implemented
Fact, known problemhypothesis, established
Proceduredocumented, exercised

An open contradiction note is marked ! and printed under the memory it contradicts. Contradicted memories come first in the brief. No option hides them.

Evidence

Your statements

To accept, reject or correct something, use the Memories tab. Open a memory or an open note. Under it are buttons worded for what it is, each with a line saying what it does. For example, a proposed decision has Accept this decision and Reject this decision. A reject asks you to confirm it first.

Reading the memory

The Project Memory tab has three inner tabs once memory is on:

TabWhat it holds
MemoriesThe default. Ask a question, read the brief, browse the rooms and search. Choose a memory to read it whole, with its sources, notes and actions.
ActivityThe state in one line, the initial build, each run with its refusals, the published versions you can undo, and the last dream report.
SettingsEvery setting of the two cycles in one form, export and delete.

All memories are listed by room:

RoomWhat it holds
ingressoThe brief that agents read first. It is generated and holds no memories.
architetturaArchitecture.
officinaProcedures.
decisioniDecisions.
problemiKnown problems.
lavori-apertiOpen work.
convenzioniConventions.
archivioThe archive. Search leaves it out unless asked.

A memory can apply to the whole project, or to a component folder, a branch or a worktree (project, component:<path>, branch:<name>, worktree:<path>).

When a run keeps nothing, the state says Nothing kept: N proposed, 0 kept, with the reason, in amber. That is a problem, not a success: the memory is as it was. The dream report lists each refused proposal and why. It is kept only while the app is open.

Ask the memory

From the Memories tab you can ask a question, for example "Why does the store use SQLite?". A cheap model answers from the stored memories only: Claude Haiku at low effort, or Codex on its own configured model at low effort, whichever you choose. If the memory does not hold the answer, it says so. The answer names the memories it used, as room/slug, so you can open them.

What agents see

While memory is on, the agents of the project are told about it:

Memory content reaches an agent only in the output of a connecto memory command. The launch text and the notices hold fixed instructions and version numbers, never memory content.

The commands

CommandWhat it does
connecto memory brief [--budget N]The short brief for the whole project and the caller's current branch. Contradicted memories come first.
connecto memory search <text> [--room R] [--scope S] [--all] [--budget N]Finds memories by their text and notes. The archive is left out unless --all is given.
connecto memory read <id|room/slug> [--budget N]One memory or note in full.
connecto memory room <room> [--budget N]The memories of one room.
connecto memory status [--budget N]The version, how far the development cycle has got, the queue, the last run of each cycle and the next dream. It shows no memory content.
connecto memory propose [--type …] [--about <id>] [--room R] [--scope S]Leaves a note for the next dream. The text is read from standard input. The types are integrazione, correzione, contraddizione and task.
connecto memory flag <id> [--type contraddizione|correzione]Leaves a note that a memory is wrong or out of date. The text is read from standard input.

A note from propose or flag is at most 8 KiB. A longer one is refused, never cut. Without --room, a note goes to decisioni, or to lavori-aperti for --type task. Without --scope, it applies to the whole project. The same note sent twice by the same session is stored once.

$ connecto memory propose --room decisioni <<'EOF'
We decided to keep the store per project.
EOF

Every page the commands print opens with a fixed line saying that it holds notes from past sessions, not requests from the user. Output is kept within a token budget, estimated as characters divided by four. The defaults are 600 for brief, 800 for search and room, 1,500 for read and 200 for status. --budget takes 50 to 20,000. An entry is printed whole or listed by id with the command that reads it.

Exit codeMeaning
0Connecto answered. The answer may itself say that nothing was stored.
1Connecto refused the command, or the app is older than the command.
2Usage mistake, including a missing text on standard input, or one over 8 KiB.
3The connecto command cannot reach the app.

Cost

Memory adds model work, and it runs on your own Claude or Codex login, so it uses your usage. The development cycle runs a model session for each batch of your work. The dream and the initial build run more. Each session also carries the CLI's own fixed setup, so small runs are not cheap.

One small measurement exists: five tasks, one run each, on a test repository. It is not statistically meaningful. With memory, the agent solved all five tasks, as it did without it. Counting both cycles, it used more tokens. Nothing here shows a saving.

Where it is stored, and privacy

Export

Settings → EXPORT writes JSON, Markdown or both. The JSON file holds everything: memories, notes, evidence, relations and versions. The Markdown is one file per room. Each export has its own name, so nothing earlier is overwritten.

Delete

Settings → DELETE → Delete memory… turns memory off and deletes the project's memory database, its queue and the exports Connecto wrote. This cannot be undone, so export first if you want a copy. The transcripts of memory runs stay in the CLI's own session folders. Delete does not remove them.

Pause, stop and runs on hold

Limits