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
- A memory for one project. It holds notes and memories, grouped in rooms. Each one keeps the sources it came from.
- It changes what an agent is told and can look up. It does not change the model.
- It stays on your computer. It is kept in a database in Connecto's data folder, never in the repository. Connecto never writes
AGENTS.mdorCLAUDE.md. - Nothing runs while Connecto is closed. There is no background service. A dream that was due while the app was closed runs once, the next time the app is open, if it is no more than 31 days late.
Turn it on
- Open the project's settings: the gear on its row in the sidebar, or right-click the project and choose Project settings….
- Open the Project Memory tab and tick Keep a memory for this project.
- 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:
| Setting | Default | Meaning |
|---|---|---|
| History | 90 days | Days of git history and conversations. |
| Input limit | 2,000,000 characters | Characters read in total. At least 12,000. |
| Time limit | 60 minutes | When 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:
- Credential files:
.envfiles, keys and certificates,.npmrc,.netrc,.git-credentialsand similar. Their names are not sent to a model either. - Dependency and build folders such as
node_modules,target,distand.venv, lock files and binaries. - Files over 1 MiB, anything reached through a symbolic link, and nested repositories and submodules.
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.
| Setting | Default | Meaning |
|---|---|---|
| Grouping window | 3600 seconds | Time 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 most | 20 | Beyond it, the queue waits. |
| Input limit | 60,000 characters | Per run. A larger batch is split, never cut. |
| Attempts | 3 | Before 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.
| Setting | Default | Meaning |
|---|---|---|
| Days | Monday to Friday | With no day chosen, it never runs on schedule. Dream now still works. |
| Time | 02:30 | Local time. |
| Time limit | 30 minutes | From the start of the dream to its publication. |
| Input limit | 200,000 characters | Per run. More is split by room. At least 5,000. |
| Minimum new items | 1 | Events 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:
| Status | Meaning |
|---|---|
candidato | Recorded with its sources, not yet independently confirmed. |
verificato | At least one independent confirmation. |
da_verificare | Something it rests on changed, or the evidence was not enough. It needs checking. It is not false. |
superato | Replaced by another memory. |
conflitto | Sources 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:
| Kind | Standings, weakest first |
|---|---|
| Decision, convention | proposed, accepted, discarded |
| Work | planned, in progress, implemented |
| Fact, known problem | hypothesis, established |
| Procedure | documented, 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
- A proposal is not a decision. A note from an agent gets the weakest standing of its kind, and only you can turn it into a decision.
- A plan is not an implementation. Work becomes implemented only from a code change Connecto observed in git, or from your statement.
- A hypothesis is not an established cause. A documented procedure is not one seen working.
- An agent repeating what it read does not verify it. Evidence from one session, or from one version of a file, counts once however often it repeats.
- What you type in a terminal is not your statement. Connecto cannot tell a typed prompt from one a CLI started on its own, so terminal text counts as something said in a session.
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.
- Accept and reject take effect at once, as a new version you can undo.
- Correct says what is right instead. Add a note… is for anything else.
- Accepting a plan or a procedure confirms it as it stands. It does not say the work is done or the procedure was run.
- A statement is bound to what you saw. If the memory changed since, it is refused, reloaded, and you confirm again.
Reading the memory
The Project Memory tab has three inner tabs once memory is on:
| Tab | What it holds |
|---|---|
| Memories | The 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. |
| Activity | The state in one line, the initial build, each run with its refusals, the published versions you can undo, and the last dream report. |
| Settings | Every setting of the two cycles in one form, export and delete. |
All memories are listed by room:
| Room | What it holds |
|---|---|
ingresso | The brief that agents read first. It is generated and holds no memories. |
architettura | Architecture. |
officina | Procedures. |
decisioni | Decisions. |
problemi | Known problems. |
lavori-aperti | Open work. |
convenzioni | Conventions. |
archivio | The 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.
- Connecto picks what the model sees: the brief, a search for the question, and the best few memories, at most about 33,000 characters. Secrets are removed first.
- The model is asked not to read project files. Nothing physically stops it, so this is an instruction.
- An answer is not a memory. It writes nothing to the memory, and it is not listed under Activity or counted in the development cycle's runs.
- A question waits at most 90 seconds. Questions are refused when memory is off, when Connecto is paused, when the question is empty or over 2,000 bytes, and when two are already waiting.
- The last 8 questions and answers are kept while the app is open.
What agents see
While memory is on, the agents of the project are told about it:
- At launch, each Claude and Codex terminal of the project is told to run
connecto memory briefbefore any work, and to propose what adds value at the end. - A conversation that started before memory was turned on gets a one-time notice when it is resumed.
- When a new version is published, each open terminal gets a short notice with its next prompt. No terminal is woken for 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
| Command | What 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 code | Meaning |
|---|---|
| 0 | Connecto answered. The answer may itself say that nothing was stored. |
| 1 | Connecto refused the command, or the app is older than the command. |
| 2 | Usage mistake, including a missing text on standard input, or one over 8 KiB. |
| 3 | The 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.
- No cost figures. The CLIs report no reliable cost, so Connecto shows none and promises no spending cap.
- Activity lists every run with its characters in and out, its duration and its outcome.
- Limits are set in runs per hour, characters per run and minutes, under Settings.
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
- Stored locally. The project's memory database and its queue live in Connecto's data folder. On macOS, exports go to
~/Library/Application Support/connecto/projects/<id>/memory/exports/. Nothing is written into the repository. - Never instruction files. Connecto does not write
AGENTS.mdorCLAUDE.md. - Redaction. Connecto removes secrets before it stores, sends to a model, prints or exports text. It removes the values of environment variables whose names end in
_API_KEY,_TOKENor_SECRET, or containPASSWORD, and common key and token formats. The Connecto vault is not used for this. - Not covered. What a memory run reads on its own, with its CLI's tools, is not filtered. It goes to the model unredacted, and into the CLI's own session log, as in any terminal of that CLI. The initial build's exclusions do not bind it.
- Redaction is best effort. It lowers the chance that a secret travels. It is not proof that none did.
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
- Pause (Pause All Agents) starts no memory run. A run already going publishes nothing, and runs again after Resume.
- Stop Everything cancels every memory run in progress. The queue is kept.
- Closing the app cancels runs. The memory stays consistent, because each write is one transaction.
- The first time a CLI runs in a folder, it asks whether you trust that folder. A memory run cannot answer that question, so it waits on hold, and Activity says why. Open a terminal for the project with that CLI once and accept. The run then resumes by itself after a short wait.
Limits
- Nothing runs while Connecto is closed.
- What you type in a terminal is never recorded as your statement. Use the Memories tab.
- A memory is a set of notes, not a complete record of the project.
- Some repositories are read without git, so the build has no history or local changes. Your system git configuration is never read.
- A prompt over 64 KiB is stored as "content not available", never cut.
- On Windows, deleting memory is refused (you remove the folder yourself), and the initial build reads file names but not their contents. The memory code has not been built or tried on Windows yet.
- Daylight-saving changes, and catching up several days with the real CLIs, have not been tried.