Introducing a new way to review your PRs.

Read the announcement

thedotmack / claude-mem

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More

View on GitHub

47 documents · Updated Nov 20, 2026

docs / teambrain-workflows

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:

RoutePurposeMain consumer
GET /api/teambrain/statusShow membership and sharing stateLocal viewer
GET /api/teambrain/boardRead the consent-filtered shared boardLocal viewer
GET /api/teambrain/briefGet project orientation as textSession start and MCP
POST /api/teambrain/searchFind shared team intelligence as textMCP

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

TriggerConsequenceGuard
TeamBrain URL is invalid or uses an unsafe plain-HTTP originThe client refuses to send the sync tokenURL and origin checks in the shared client
Sync credentials are missingBrief, search, status, or board calls fail without a cloud requestJoin flow writes the sync connection; client returns a setup error
TeamBrain host times out during SessionStartThe session continues without shared context or with one bounded reasonTwo-second brief budget and bounded failure text
Team membership is removed upstreamShared reads return a membership failure and the local view cannot use stale accessWorker maps not_a_member to 404 and reports the join fix
MCP client runs before the install joins a teamTeam tools are absent or return a setup errorAdvertisement filter and call-time guard
Shared context fills the host output budgetThe brief is shortened or omittedReserved space, clipping, and explicit omission notices

Key files

FileWhy to read it
src/…/teambrain.tsShared connection rules, authenticated calls, response limits, and failure contract
src/…/teambrain.tsTeam creation, joining, sharing, status, and leaving workflows
src/…/context.tsSession-start brief timing, placement, and budget behavior
src/…/TeamBrainRoutes.tsLocal HTTP boundary for status, board, brief, and search
src/…/mcp-server.tsteam_brief and team_search tool contracts and worker forwarding
src/…/mcp-tool-visibility.tsConditions that advertise TeamBrain tools to MCP clients
src/…/worker-service.tsWorker registration point for TeamBrain routes
docs/…/teambrain.mdxUser-facing distinction between shared TeamBrain work and private local work