What it reads, what it writes, what to do with it

The two halves

The engine reads your work and writes memories. The viewer draws them. They ship as one download and share one file: the engine writes it, the viewer opens it read-only, and neither knows anything about a network.

Everything that changes the mind happens through the engine, on purpose. The signal-strength formula and the rule that traces are mandatory live in one place; a second implementation inside the app is how the two would start disagreeing about who you are.

What it reads

Only what is already on your machine, and only what you switch on:

• Assistant histories

  Claude Code, Codex and Gemini CLI sessions, and ChatGPT or Claude exports you have downloaded. What you asked for, and what you corrected.

• Notes

  Apple Notes, or any folder of markdown — an Obsidian vault, a Notion export. What you write when nobody is asking.

• Messages

  Only what you wrote. The query never selects the other person's rows; their words are not filtered out afterwards, they are never read. Same for a WhatsApp export.

• Git

  Your commits, by author. The habits that show up in code rather than in conversation.

Notes and Messages sit in files macOS protects, so they need Full Disk Access. Without it those two go unread and the mind rests on less; nothing breaks and nothing is hidden from you.

The five layers

Every memory belongs to exactly one. The distinction is the reason the output is not a pile of notes.

• Values

  What you will not trade away. Slow to appear, slow to change, and the least likely to be wrong.

• Patterns

  What you do repeatedly, whether or not you would describe yourself that way. The largest layer by some distance.

• Voice

  How you say things — length, directness, what you refuse to pad.

• Preferences

  What you reach for when nothing forces your hand. A preference is not a value; the engine will not promote one into the other.

• Current state

  What is true this month. Deliberately separated so a passing mood never gets treated as a fact about you.

Signal strength, and why memories disappear

Each memory carries a signal strength the engine derives from how many traces support it and how many contradict it. Nothing below 0.35 is written at all. In the app, Settings → Identity raises that floor further if you want to see only what the engine would defend — the count of what is being hidden is always in the top bar, because looking at part of your mind without knowing it is worse than not looking.

A memory seen exactly once is held back as a draft rather than published. Two memories in conflict become a question in the inbox instead of a silent resolution.

Disagreeing with a memory

Click any node. The panel shows the memory, its layer, its signal strength, and the traces it grew from — the actual messages, with the corrections marked. If it is wrong, the traces usually show why.

• Hide a cortex

  It stays in the database and stops appearing. Hiding says “this is not me”, not “delete the record”.

• Merge two cortices

  When the engine has split one cortex into two, merging teaches it the boundary.

• Answer a conflict

  The inbox queues them. Answering settles the memory and tells the engine which reading to trust next time.

• Confirm or drop a draft

  Single-trace memories wait in the inbox until you say whether they are real.

Handing it to an assistant

The mind is more useful in the tools you already work in than in a window of its own. Settings → Assistants lists the clients it finds on this machine — Claude, Claude Code, Cursor, Windsurf, VS Code — and connects any of them with one button, leaving whatever servers they already had alone. Anything else takes the snippet beside it, or the bundle if it installs extensions itself. From a terminal the same thing is coredence connect.

What the assistant gets is a way to ask rather than a file to read: what you think about a subject, which memories cover it, and which traces any one of them grew from. It is read-only. An assistant can quote your mind and disagree with it, but it cannot edit it — deciding who you are stays with you.

The server runs on your machine. The client starts it and talks to it over a pipe, so there is no account, no key and nothing listening on a port.

And it does not have to hand over everything. Settings → Assistants decides what an assistant may see:

• Traces, in three degrees

  With the text, or only how many moments a memory rests on and when they were, or nothing at all. Asking why a memory exists need not mean reading the message it grew from.

• A signal-strength floor of its own

  Separate from the one the neural map draws with. What you want to look at and what you hand out need not be the same.

• Cortices held back

  A hidden cortex takes its memories with it. Hiding the heading and leaving the memories would be hiding nothing.

Keeping it up to date

Every hour the consolidation cycle reads your sources again, and it runs whether or not the app is open. Consolidation does not happen on every cycle: every window carries all of your memories, so sending a half-empty one spends most of the allowance on context that repeats. The cycle waits until a window fills or a day goes by, and Settings says what it is waiting for. If you do not want to wait, run one by hand whenever you like (⇧⌘R on a Mac, Ctrl+Shift+R on Windows); Settings → Engine turns the schedule off if you would rather the neural map held still. The map watches the database and redraws itself as soon as the engine writes, so you can leave the window open while a cycle runs.

What it costs

Consolidating means paying a model, and you should know what that costs before it happens. The engine does not guess: it splits the waiting events into windows, builds the prompts it would send, and counts the tokens — without making a single call.

• coredence cost

  How many events, how many windows, and three figures: as the engine works today, with the repeated context cached, and through the batch queue. Settings → Waiting to be distilled shows the same numbers in the window.

• The size of your mind drives the cost

  This is the surprising part: the context repeated in every window — the list of existing memories, the cortices, the taxonomy — is most of the prompt. Measured on a mind of 457 memories, it was 63% of it. So consolidating gets more expensive as the mind grows, even when the number of events stays the same.

• coredence distill --batch

  For work that is not urgent: the windows go to the batch queue, the repeated context is paid for once, and the total drops noticeably. In return the result can take up to 24 hours; you do not have to wait for it, the consolidation cycle collects it when it is ready. To take it by hand, coredence collect.

• Your own key has no ceiling

  The plan is a convenience: we pay for the model call and give you a monthly allowance. With your own key there is no allowance — you use it at cost, and that door is on the screen that tells you the allowance ran out.

• The same token count means three different things

  With your own key you pay your provider per token, and the screen shows an amount. On an installed Claude subscription there is no extra charge: it comes out of that subscription's allowance. On a plan it comes out of your monthly allowance. Showing a dollar figure to all three would invent a cost for two of them, so the screen says whichever one you are on.

Every one of these numbers is measured; none of them was set by guessing, and they are updated when the measurement is.

On Windows

The installer brings both the engine and the window. The window shows you the mind; your assistants read it over MCP as well, so you can ask one what it knows about you. If you would rather not install anything, the zip carries the engine alone — no window there, and the command is called coredence.bat.

• The installer

  Double-click and it is done. It installs into your own user directory, so no administrator rights and no UAC prompt; it adds itself to your PATH, and it opens the Coredence window when it finishes, where first-time setup happens.

• coredence status

  What the mind holds, and when it last grew.

• coredence rule <words>

  Searches the memories; give it a name and it shows that one memory with its numbers and the real moments behind it. How you ask where a sentence in the skill file came from.

• coredence connect

  Lists the clients it finds on the machine; --all connects every one of them.

• coredence uninstall

  Removes the consolidation cycle and the client connections. Your mind stays; --everything deletes it.

• %USERPROFILE%\.coredence

  The mind, the profile and the consolidation cycle's log. The same directory the Mac uses, in the same format, so a mind consolidated on one machine can be carried to the other.

Consolidation needs a model. If Claude Code is installed it is used; otherwise setup asks for an API key. It continues without one — sources are read, assistants are connected, and consolidation waits. One other difference: Windows does not apply file permissions the way POSIX does, so the profile carrying the key may be readable by other users of the machine, and the engine says so the first time it writes it.

Where things live

• ~/.coredence/coredence.db

  The mind. One SQLite file. Copy it, back it up, open it with any SQLite browser, or delete it.

• ~/.coredence/profile.toml

  What it may read, and which model it thinks with. Your API key lives here, in a file only you can read.

• The window never opens a socket

  Check with lsof -i -a -p $(pgrep -x Coredence) and it prints nothing. The side that reaches the network is the engine, and it does so for two things: it calls the model you chose while consolidating, and once a day it asks github.com which release is the latest — that request carries nothing that identifies you, and coredence updates off stops it. Point the model at your own machine and the first one stops too.

• Settings → Engine

  Points the app at a different database, and turns off the automatic refresh if you would rather the map held still.

Anything not covered here belongs in the issue tracker. If something on this page is wrong or missing, say so.