feat(workspace): mirror memory blocks to the bound workspace

Merged
SA
3mo ago
+2987-30

Summary

Adds cloud persistence for Altimate Code memory: blocks are written to the workspace a project is bound to, and loaded back at session start.

Local Markdown files remain authoritative — this is additive, and every cloud call is fire-and-forget so a failure can neither fail nor slow a local memory save. Gated on the workspace pilot flag, and inert until a project is bound to a workspace that has memory enabled.

Stacked on #1100.

Write

A saved block is pushed and tagged with its workspace. A create runs an extractor server-side that rewrites the text, so each create is followed by an update that restores the block verbatim — the update path does not run the extractor. The create response carries the new record's id, so no enumeration is needed to learn it.

Before creating, an unindexed block is looked up by logical identity — source, scope, block id, workspace, project — and adopted if it already exists. That is what makes a second machine, a reinstalled CLI, or a create whose response was lost update the existing record rather than duplicate it. Content is deliberately excluded from that identity: a key that moved when content changed could never find the record it means to update.

Read

One fetch per session, held in memory and merged at injection with local blocks winning. Nothing is written to disk, since a cloud record may have been edited by a client that does not preserve this CLI's metadata. Injection runs on every step, so the fetch is started once at session start and the merge applies a bounded wait rather than any per-step network call.

Retrieval is workspace-wide: every project-level block for the workspace is returned regardless of which project wrote it, plus the account's global blocks, which carry no workspace and apply everywhere. Blocks from a sibling project are labelled with their origin so the model does not read them as this project's.

Scoping and lifecycle

Project blockscarry the workspace and the originating project
Global blockscarry neither — they apply in every workspace
Project identitygit remote where there is one, else the directory — the same rule the binding uses, so two machines cloning a repo the same way converge on one record
Privacyevery record marked private; nothing enforces it yet, and the marker exists so a later sharing feature can promote without a backfill
Deletearchives the cloud record rather than removing it, so history survives
Bindsweeps existing blocks so memory written before the bind is not stranded

The workspace's memory toggle is honoured in both directions, and only an enabled verdict is cached — a workspace starts with memory off, so caching the disabled verdict would ignore the user switching it on.

Training blocks are normalised before hashing: the applied counter embedded in their body is rewritten on every session start, and without that a mirror would issue a request per training block per session for a change no reader sees. Remote blocks never drive the applied counter, which writes to the local store and would fabricate a file for a block this machine never had.

Verification

Verified end to end against a live workspace:

  • the memory toggle blocks a freshly created workspace, and works once enabled
  • both scopes store verbatim
  • hydration returns them with the right scoping
  • a local delete archives the record and drops it from the next session

45 unit tests, mutation-checked. Removing any of these fails the suite: the memory toggle, the binding requirement, training-counter normalisation, lookup-before-create, the source filter on read, workspace scoping, the global-applies-everywhere rule, account scoping of the index, or the read opt-in.

Full suite: 11239 pass / 1 fail — the failure is Truncate > cleanup, which fails identically on the base branch with these changes stashed.

Depends on

A backend change that surfaces memory record ids and adds the client-source filter this client opts into. Until that lands, creates return no id and reads come back empty.

🤖 Generated with Claude Code

https://claude.ai/code/session_012wmN54fRA4WLgdVJVunaNk


Summary by cubic

Mirrors local memory blocks to the bound workspace and hydrates workspace memory into sessions. Local Markdown remains authoritative; cloud sync is best‑effort and never blocks saves.

  • Write path: adopts existing records by logical identity (source/scope/id/workspace/project); create then update to restore verbatim after extractor rewrites; sha‑256 unchanged check; per‑block serialized cloud ops prevent delete/mirror races; delete maps to archive; skips when the local block no longer exists or the remote view is truncated; robust tag handling; training meta normalised for stable hashes.

  • Read path: one fetch per session; overlay keyed by sessionID with local blocks winning; TTL (expires) is mirrored and enforced; sibling‑project blocks are labelled; remote blocks never increment training counters.

  • Backfill: runs only on first bind or identity change; the CLI link flow now awaits it; success writes seededAt; declined blocks count as failures; avoids reviving archived items and reads deletes through the known‑records view with a truncation warning.

  • State/API: binding cache canonicalizes paths and adds seededAt; cache is scoped per tenant+API URL and credential; MemoryStore.list/read accept an explicit directory; exported altimateRequest shares typed wire helpers.

  • Gating and UX: inert unless the pilot flag is on, the project is bound, and workspace memory is enabled (only a positive enable verdict is cached). Requires backend memory endpoints that return record ids and support client‑source filtering. Browser handoff opens <tenant>.ws.myaltimate.com/create-and-link with loopback return, CSRF/state checks, 15‑min timeout, and port walk 7317..7325; confirmation dialog replaces toasts, the sidebar shows the linked workspace (and “(pinned via --workspace)” when applicable), and the manage URL is shown on success.

Summary by CodeRabbit

  • New Features
    • Added workspace linking with interactive setup, project rebinding, and browser-assisted configuration.
    • Added cloud workspace memory synchronization, including mirroring, archival, hydration, and backfill.
    • Workspace memory now appears in prompts, while local content takes precedence when both exist.
    • Added resilient local workspace binding and synchronization state management.
  • Bug Fixes
    • Improved handling of missing, expired, declined, truncated, and conflicting memory records.
    • Preserved local memory operations when cloud synchronization fails.