Collossal MCP

Shared memory for coding agents. Runs on a developer's machine and talks to the Collossal API over HTTPS — it holds an API key and never database credentials.

Setup

One command per machine — the dashboard's Setup page shows it with your addresses filled in:

curl -fsSL https://<your-collossal>/install.sh | sh -s -- --api-url https://<your-collossal>/api/v1

That installs the collossal command (with uv, which brings its own Python) and runs collossal install, which:

1. Signs the machine in through the browser. It shows a code and opens the dashboard; you check the code and approve. The machine receives an API key of your own — nothing to copy — saved to ~/.collossal/config.json (0600).
2. Sets up Claude Code for every project: the hooks below go into ~/.claude/settings.json (your other settings are kept, and the original is backed up once), and the MCP server is registered with claude mcp add --scope user.
3. Uploads your past sessions from ~/.claude/projects — every one, whatever it ran in — with their real timestamps, titles and redaction, so your history appears on the dashboard, not just what happens from now on.

From then on every Claude Code session on the machine streams to your team's Sessions tab as it happens, and every teammate can open it. Nothing has to be connected first: a session is labelled by the repository it ran in (or, begun in a folder holding several, the one it works in most), or by its folder. A repository connected to a project additionally gets memory — decisions anchored to its files.

Each person chooses which of their sessions the team sees, under Sessions → Configure: all of them (the default), or only those in the repositories and folders they pick. The choice applies at once to past sessions as well as new ones. A session outside it is still recorded, and its owner still sees it under My sessions — nobody else does: not teammates, not workspace admins, not an agent's team_sessions or a handoff. Setting it before running the installer keeps the upload of past sessions within it from the start.

Until the CLI is published, install it from this checkout instead:

uv tool install --editable /path/to/main-mcp && collossal install --api-url http://localhost:3000/api/v1

Command	Does
collossal install	All of the above; safe to run again
collossal import	Upload past sessions again — e.g. after connecting another repo
collossal status	Who this machine is signed in as, and what is set up
collossal doctor	The same, plus what is wrong and how to fix it
collossal login	Sign in again without changing anything else
collossal uninstall	Remove the hooks, the MCP server and the sign-in

COLLOSSAL_API_KEY and COLLOSSAL_API_URL still work and take precedence over the saved sign-in — for CI, or to pin one project to a different workspace.

Tools

memory_write — records a decision and anchors it to the files it governs.

memory_search — natural-language search across the project. Results can come from a different repository than the one being edited; that is the point.

memory_for_files — decisions attached to specific files. Needs no query, so it surfaces context an agent would not have known to search for. Anchors belong to a repo, so this looks within the current one; memory_search is the cross-repo path.

team_sessions — teammates' recent agent sessions, to inherit from. Lists the whole workspace's, whatever repository or folder they ran in; excludes your own and any a teammate keeps private, and omits sessions that recorded nothing — an empty run is noise in a list an agent acts on.

session_handoff — takes a teammate's session over: where the work is, the end of their conversation, and the decisions already anchored to the files involved, written for the receiving agent to read on its first turn. Accepts a session id or a pasted dashboard link. No agent will adopt a foreign session id, so what transfers is the context, not the process.

The agent supplies the claim, rationale, and files. Everything identifying — repo, branch, commit, project — is read from the git checkout, because asking an agent for a project id invites it to guess.

File paths are normalised to repo-relative before storage: an absolute path would anchor the memory to one machine's directory layout and never match for a teammate.

A decision replaced by a newer one is still returned, labelled [SUPERSEDED] with the claim that replaced it, stated before its rationale — an agent must not be able to read stale reasoning without first seeing that it no longer holds.

Automatic capture

Two hooks, because the transcript on disk already holds every tool call and message — there is nothing to gain from hooking each tool.

Hook	Does
SessionStart	Injects this project's decisions into the new session, and starts streaming it to the dashboard
Stop	Captures what the turn taught, and delivers any instruction a teammate sent
SessionEnd	Ships the rest of the transcript, and uploads the whole session if it was never streamed — one that began before Collossal was installed

collossal install puts them in ~/.claude/settings.json for every project. To set them up by hand instead, merge hooks.example.json there, or into one project's .claude/settings.json to scope them to that repo — but not both, or that project's sessions are streamed twice.

How a session becomes memory

The worker reads from the last cursor, then looks for four mechanically detectable moments — nothing here calls a model:

• FAILURE_FIX — a command failed, edits followed, the same command passed. Matched on command shape rather than exact text, because an agent re-runs the same tool against a different file rather than retyping the failure.
• REVERSAL — one file rewritten six or more times, with the reasoning stated nearest the final edit. Fewer than six is ordinary iteration.
• USER_CORRECTION — the user pushed back right after an assistant action.
• STATED_CONSTRAINT — the user stated a rule.

A session reaching none of these is dropped having cost one file read. Measured across 78 real transcripts (296 MB), that gate discards 39% for free and the rest yield about 6 windows each.

Windows are stored separately from decisions, so the store of durable claims never fills with unprocessed transcript fragments. A stub promotes FAILURE_FIX windows to decisions at confidence 0.4; injection ignores anything below 0.5, so raw machine guesses never reach an agent's context before distillation exists.

Redaction

Credentials are stripped in the worker, immediately before the push — not on the server, because scanning there would still mean the secret crossed the network and landed in a request log.

Three layers: known vendor formats (Anthropic, OpenAI, GitHub, AWS, Slack, Google, Stripe, JWTs, private keys, connection strings), assignments whose name claims to hold a credential (API_KEY=, SECRET=), and a Shannon entropy fallback for credentials with no recognisable shape.

The trade is deliberately asymmetric: a false positive costs a slightly less readable memory, a false negative puts a live credential in a database forever.

Measured against 564 fields from real transcripts: zero false positives, and zero secrets missed across a suite of 15 credential formats. Absolute paths are rewritten repo-relative in the same pass, so memory does not carry one machine's directory layout to everyone else.

Safety properties

The hook always exits 0 and swallows every error to ~/.collossal/hook.log. It cannot fail a session, and with the API unreachable a session starts normally with no memory rather than an error.

Live sessions

A workspace admin can watch a session as it happens and step into it.

Piece	Does
tailer.py	Spawned at SessionStart, detached. Follows the transcript, redacts, and pushes render-ready events plus snapshots of uncommitted work — git diff, and files not yet added — which a session's Changes tab and the workspace owner's Code diff view show. An empty snapshot means the tree is clean again.
Stop hook	Collects instructions queued from the dashboard and hands them to the agent as its next input.

Two properties worth knowing.

It tails, it does not replay. The tailer starts from the current end of the transcript. A hook firing on a resumed session would otherwise push its entire history — megabytes — as though it had all just happened.

Instructions arrive at a turn boundary, not instantly. There is no way to interrupt a turn already running, so anything sent is queued and delivered the moment the agent would otherwise have stopped. Delivered exactly once: a repeated instruction would have the agent redo work.

Everything streamed is redacted on the machine first, and absolute paths are rewritten repo-relative — a watcher sees the repository, not someone's home directory. Events are kept for SESSION_RETENTION_DAYS (90 days by default), so a session can be read back after it ends; the durable record of a session remains the decisions distilled from it.

Sending an instruction also writes a NOTICE into the stream the watched person can see. Being observed and redirected with no indication of it is not something to ship.

Layout

config.py       env, validated once at startup
git_context.py  repo/branch/commit discovery and path normalisation
client.py       Collossal API client
format.py       renders decisions for a context window
server.py       MCPServer and the tools
capture/
  hook.py       lifecycle hook: injection, and spawning the worker
  worker.py     detached — reads transcript, gates, ships
  transcript.py streaming JSONL reader
  windows.py    the four detectors
  redact.py     strips credentials before anything leaves the machine
  ship.py       API calls for capture and injection