TeamBrain workflows
TeamBrain connects a local claude-mem install to a shared team view of project work. It lets a member choose what to share, receive a short project brief at session start, and ask an agent about team-shared observations without mixing that work into private local memory.
System boundary
TeamBrain uses the install's existing cloud sync identity. A TeamBrain connection is active when the install has a TeamBrain host URL; requests then carry the sync token and sync user ID to that host. The local worker acts as a controlled proxy, so agents and local clients do not handle cloud credentials directly. The hosted board and its access rules remain the source of shared project intelligence. src/…/teambrain.ts• L44-68 src/…/TeamBrainRoutes.ts• L34-47
The connection is read-only for shared intelligence. Membership commands can change the sharing choice, but brief, search, status, and board reads do not change private memory or local review state. This keeps TeamBrain beside the local workspace rather than turning the two into one data set. TeamBrain and work-view collaboration describes that wider separation; Work-view experience covers the human review surface.
Connection and sharing lifecycle
Team membership
The membership flow starts in the terminal or browser and ends with a local connection that names the selected team. teambrain start opens team creation in the hosted workspace. teambrain join redeems an invite through device approval, preserves the install's existing observer and provider choices, and records the sync and TeamBrain connection. The member then chooses no projects, named projects, or all current and future projects to share. src/…/teambrain.ts• L544-641
The share choice is explicit and can be changed later with teambrain share. Leaving a team removes the projects that this member shared. If the account belongs to another team, the install can retain that TeamBrain connection; if it belongs to no team, TeamBrain is turned off locally. src/…/teambrain.ts• L644-671 src/…/teambrain.ts• L697-753
The following diagram shows how a local membership choice becomes a shared project scope.
flowchart LR
A[Create or accept invite] --> B[Approve device]
B --> C[Save sync and TeamBrain connection]
C --> D{Choose scope}
D -->|No projects| E[Share nothing]
D -->|Named projects| F[Share selected projects]
D -->|All projects| G[Share current and future projects]
E --> H[TeamBrain host]
F --> H
G --> H
References: src/…/teambrain.ts• L544-641 src/…/teambrain.ts• L644-753
Authenticated client calls
The shared TeamBrain client turns local settings into authenticated requests to the TeamBrain host. It validates the destination before sending the sync token, uses HTTPS except for approved local development origins, does not follow redirects, and converts timeouts or malformed replies into short safe error messages. This gives the CLI, worker, and session-start hook one failure contract. src/…/teambrain.ts• L243-299
The client exposes two groups of calls:
- Team control: list memberships, read the consent-filtered board, change project sharing, and leave a team.
- Team intelligence: fetch a project brief and search the observations that teammates shared.
The client uses the same identity for both groups. This prevents a local view from claiming a different team identity than the install that syncs the account. src/…/teambrain.ts• L381-476
References: src/…/teambrain.ts• L58-68 src/…/teambrain.ts• L243-299 src/…/teambrain.ts• L381-476
Agent entrypoints
Command entrypoint
The npx claude-mem teambrain command is the human control plane for TeamBrain. It supports team creation, invite-based joining, membership status, sharing changes, and leaving. It also checks that the settings file can be read and refuses to switch an install that already syncs as another account. src/…/index.ts• L65-68 src/…/teambrain.ts• L160-226
After a join, the next session can receive a team brief and the MCP server can advertise team tools. The command therefore establishes the connection and sharing consent; it does not itself inject team context into an agent. src/…/teambrain.ts• L624-641
References: src/…/index.ts• L232-235 src/…/teambrain.ts• L90-98 src/…/teambrain.ts• L544-641
MCP entrypoint
The MCP server exposes team_brief and team_search as read-only agent tools. It advertises them only after the install has joined a team. A call then goes to the local worker, which applies the same TeamBrain client and returns plain text suited to model context. src/…/mcp-server.ts• L766-797 src/…/mcp-server.ts• L1170-1213
This visibility rule gives an unjoined install a clean tool list instead of tools that can only report missing setup. The call guard remains in place as a second boundary for clients that try to call a hidden tool. src/…/mcp-tool-visibility.ts• L50-67
References: src/…/mcp-server.ts• L766-797 src/…/mcp-server.ts• L1170-1213 src/…/mcp-tool-visibility.ts• L50-67
Shared brief delivery
Session-start brief
At a new session, the hook asks the TeamBrain host for information related to the current project while it obtains local context. The result is appended after local context as a marked information block, so the agent can distinguish teammate knowledge from instructions. A resumed Claude session does not request a new brief because it must preserve the existing conversation. src/…/context.ts• L164-169 src/…/context.ts• L331-338
The brief has a short time budget and a bounded size. If the host is slow or unavailable, the hook adds one plain reason rather than failing the session. If the context budget is nearly full, it cuts the brief or reports that it was left out. src/…/context.ts• L49-90 src/…/teambrain.ts• L24-42
The following diagram shows the session-start relationship between private context and shared team context.
sequenceDiagram
participant H as SessionStart hook
participant L as Local context source
participant T as TeamBrain host
participant A as Agent
par Read private context
H->>L: Request project context
L-->>H: Local context
and Read shared context
H->>T: Brief for current project
T-->>H: Team brief or bounded failure
end
H->>A: Local context plus marked TeamBrain information
References: src/…/context.ts• L49-90 src/…/context.ts• L157-169 src/…/context.ts• L331-338 src/…/teambrain.ts• L317-340
Brief and search responses
The brief endpoint answers with a project-focused summary. The search endpoint answers a question across the observations, plans, and decisions that the team shared. Both responses are plain text at the worker boundary, and both use an empty-result message when the team has no matching information. src/…/TeamBrainRoutes.ts• L72-102
The brief and search paths serve different moments in the workflow. The brief gives passive orientation at session start; team_search gives an agent an explicit lookup path when it needs a detail or owner. Neither path changes what the member has shared. src/…/teambrain.ts• L317-360
References: src/…/TeamBrainRoutes.ts• L72-102 src/…/teambrain.ts• L317-360
Worker HTTP boundary
Local proxy routes
The worker exposes a small local TeamBrain API for the viewer and agent entrypoints. Status and board reads are loopback-only because they support the local work view. Brief and search are agent-facing routes, so they validate input, proxy the request with the install's credentials, and return text. src/…/TeamBrainRoutes.ts• L19-47
The route boundary keeps local clients independent from the hosted API shape. It reports setup state as a clear conflict response, maps a timeout to 504, maps a missing membership to 404, and maps other upstream failures to 502. It does not expose the sync token in any response. src/…/TeamBrainRoutes.ts• L49-70 src/…/TeamBrainRoutes.ts• L104-126
The main route purposes are:
| Route | Purpose | Main consumer |
|---|---|---|
GET /api/teambrain/status | Show membership and sharing state | Local viewer |
GET /api/teambrain/board | Read the consent-filtered shared board | Local viewer |
GET /api/teambrain/brief | Get project orientation as text | Session start and MCP |
POST /api/teambrain/search | Find shared team intelligence as text | MCP |
References: src/…/TeamBrainRoutes.ts• L34-47 src/…/TeamBrainRoutes.ts• L49-126 src/…/worker-service.ts• L881-887
Board access
The board route gives the local viewer the shared work lists, tasks, and findings that the TeamBrain host permits for the requesting identity. The worker checks the team ID and validates the returned board shape before it reaches the local panel. This protects the viewer from invalid remote data while preserving membership and inactive-team refusals. src/…/teambrain.ts• L397-443 src/…/TeamBrainRoutes.ts• L59-70
Board reads use the install's sync identity and do not alter local settings. The viewer can therefore inspect shared work without receiving cloud credentials or changing private memory. tests/…/teambrain-routes.test.ts• L74-103
References: src/…/teambrain.ts• L397-443 src/…/TeamBrainRoutes.ts• L59-70 tests/…/teambrain-routes.test.ts• L74-103
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the TeamBrain host paths and the worker proxy paths aligned for brief, search, status, board, membership, and leave calls.
- Preserve the rule that the sync token is sent only to the validated TeamBrain host and never returned through worker or viewer responses.
- Keep MCP tool advertisement and MCP call guards in agreement when TeamBrain setup rules change.
- Keep the session-start budget reservation aligned with brief size limits and the host context output limit.
- Keep leave behavior aligned with the account's remaining team memberships and the special seat-only sync behavior.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| TeamBrain URL is invalid or uses an unsafe plain-HTTP origin | The client refuses to send the sync token | URL and origin checks in the shared client |
| Sync credentials are missing | Brief, search, status, or board calls fail without a cloud request | Join flow writes the sync connection; client returns a setup error |
| TeamBrain host times out during SessionStart | The session continues without shared context or with one bounded reason | Two-second brief budget and bounded failure text |
| Team membership is removed upstream | Shared reads return a membership failure and the local view cannot use stale access | Worker maps not_a_member to 404 and reports the join fix |
| MCP client runs before the install joins a team | Team tools are absent or return a setup error | Advertisement filter and call-time guard |
| Shared context fills the host output budget | The brief is shortened or omitted | Reserved space, clipping, and explicit omission notices |
Key files
| File | Why to read it |
|---|---|
| src/…/teambrain.ts | Shared connection rules, authenticated calls, response limits, and failure contract |
| src/…/teambrain.ts | Team creation, joining, sharing, status, and leaving workflows |
| src/…/context.ts | Session-start brief timing, placement, and budget behavior |
| src/…/TeamBrainRoutes.ts | Local HTTP boundary for status, board, brief, and search |
| src/…/mcp-server.ts | team_brief and team_search tool contracts and worker forwarding |
| src/…/mcp-tool-visibility.ts | Conditions that advertise TeamBrain tools to MCP clients |
| src/…/worker-service.ts | Worker registration point for TeamBrain routes |
| docs/…/teambrain.mdx | User-facing distinction between shared TeamBrain work and private local work |