architecture

Memory (Project Brain)

How the project's shared brain — prompts, MCPs, recaps, project knowledge — is stored and surfaced.

What Memory is, mechanically

Two surfaces, one purpose:

1. A SaaS-side store (Postgres + object storage). Holds the durable spine of every project: members, nodes, Threads, recaps, and — from Phase 2 onward — promoted prompts, MCP definitions, and reusable skills.
2. A project-local layer (Phase 2+): a .memory/ directory at the project root, committed to VCS, that mirrors Memory items so the project travels with its brain even when the SaaS is unreachable.

In v0.1, only the SaaS store exists. The local layer follows when there’s enough demand to merit the round-trip back-and-forth between the project and the cloud.

What lives in Memory (v0.1 vs Phase 2+)

Recaps are the central v0.1 deliverable from Memory. The rest is what makes Memory the “shared brain” once teams accumulate enough material to share.

How Recaps work (the v0.1 path)

When a Thread ends on a Node, the Node calls a Manifoldone-managed LLM gateway with the Thread’s event log (prompts, tool calls, file paths — never raw file contents). The gateway returns a one-paragraph summary. The Node POSTs that summary into Memory as a Recap row, indexed by Thread.

Anyone in the project can later open the Thread in the dashboard and read the recap, even if they weren’t subscribed when the Thread was live.

The full pipeline (with security rationale for why raw events don’t end up in the database) is in tech_architecture.md §5.

How Nodes consume Memory (Phase 2+ shape)

Once the prompt/MCP/skill library exists, when a Node dispatches an intent to the agent, it composes the agent’s context from three layers:

1. System defaults — the standard Claude Code skills and tools.
2. Memory overlays — the project’s promoted prompts, MCPs, skills, and accumulated knowledge.
3. Thread-specific intent — the prompt the user just typed.

Result: an agent on a brand-new node behaves the same as an agent on a long-running one, because both are reading the same overlay.

Permissions (Phase 2+)

Items in Memory have a scope:

• project — visible to every docked node on the project.
• branch — visible only when the working branch matches.
• user — visible only to the user who created it (used for personal experiments before they’re promoted to project scope).

Promoting a personal prompt to project scope is a deliberate action. In the project-local layer it shows up as a manifest change reviewable in a PR.

Marketplace (Phase 3)

A Memory item can declare an import reference to a published item (@team-name/skill-name). Memory resolves the reference at Thread-context-composition time. Published items are versioned; teams pin versions like any other dependency.

What’s parked

• Memory browser UI — the dashboard view that lets a director curate the project’s brain. Phase 2.
• Conflict handling for shared knowledge updates — when two nodes promote conflicting items simultaneously, the early plan is last-write-wins; refinement when there’s real usage.

Naming note

Memory was previously called “Aerepo” (Aether + Repo) in earlier drafts. We renamed it for clarity — Memory says what it does and lines up with the existing “Same Brain” pillar.