Caimeo Brainstack

Git-backed shared memory

Brainstack lets the AI tools you already use share context without moving your brain into a hosted assistant. Codex, Claude, Cursor, scripts, and private workers read the same repo-backed memory, while Brainstack adds search, proposals, skills, hooks, and local capabilities around it.

Try the local proof Install Brainstack

Smallest proof

Try the core loop before wiring a fleet

The cleanest first touch is a disposable local smoke: clone Brainstack, let the CLI create a temporary shared-brain repo under /tmp, run doctor, and build the local search index. No Telegram bot, worker, or Tailscale exposure is needed for this proof.

Local product smoke

git clone https://github.com/Caimeo-com/brainstack ~/brainstack
cd ~/brainstack
bun install --frozen-lockfile
bun run packages/brainctl/src/main.ts smoke   --profile single-node   --config examples/single-node.yaml
Why this first? It proves the shared-brain shape, search index, generated runtime files, and doctor path without asking you to trust a permanent service. The release installer and Mac app are the normal paths once you are ready to enroll a real machine.

What it is

A private shared brain for tools and machines

Brainstack gives agent tools a durable place to remember what happened, save useful context, and find it again. The source of truth is a git repo with markdown, skills, transcripts, and artifacts. Brainstack adds local search, write paths, health checks, client bootstrap, optional Telegram control, file relay, and worker routing.

Product code and brain data stay separate

The Brainstack repo contains the services and CLI. Your shared brain remains its own repo. That split matters: upgrades can refresh services and runtime files without rewriting the knowledge base your tools depend on.

  • braindLocal service that lets tools search and read the shared brain.
  • brainctlCLI for provisioning, enrollment, health checks, backups, recovery, and file relay.
  • client bootstrapCodex gets installable Brainstack skills; Claude and Cursor get checked-in shared-brain guidance.
  • telemuxOptional Telegram topics mapped to durable work contexts and file delivery.

Curated memory

Evidence becomes proposals before it becomes memory

Most tools call any saved note "memory." Brainstack keeps the raw evidence, then asks the curator to turn it into scoped, reviewable changes that future agents can understand without the original chat.

1. Work happens A harness writes a checkpoint, transcript summary, artifact, or explicit remember candidate.
2. Evidence is stored Brainstack keeps provenance: repo, machine, harness, source refs, and the raw material behind the claim.
3. Curator proposes Useful lessons become scoped proposals with applicability, non-applicability, confidence, and review metadata.
4. Operators accept or reject Accepted proposals update the wiki or memory cards. Vague, stale, or risky items stay out of future context.
Trust win: This is why Brainstack can compound without appending every chat ending to the prompt. Raw material is evidence; reviewed proposals are durable memory.

How it works

Three simple pieces

1

Git is the memory

Everything you store, from LLM chat transcripts to markdown pages, skills, notes, and artifacts, lives in the shared-brain repo and feeds fast local search.

2

Tools share the same context

Codex, Claude, Cursor, and scripts can all read the same memory instead of each tool starting over with its own scattered notes.

3

Your machines do the work

Run jobs on your own Mac, Linux box, or private tailnet workers. Telegram is optional; it is just a phone-friendly control surface.

Pick your first win

Different users should not start in the same runbook

Brainstack can become a fleet control layer, but the first outcome should be smaller: stop re-explaining work, prove safer memory, or get a Mac client enrolled cleanly.

Solo developer Run a local proof, then let Codex reuse project context instead of starting cold every thread. Mac + Codex user Install once, paste an invite, refresh skills and hooks, then watch status from the menu bar. SRE or incident lead Turn incident notes, traces, and fixes into reviewed runbook proposals instead of scattered chat lore. Team lead Check the read/write boundary, tokens, fail-open hooks, and private-network assumptions before a pilot. Self-hoster Own the repo, import existing skills and rules, and keep shared context portable across harnesses.

Docs

Choose the right Brainstack setup path

Brainstack has a lot of operating surface: install roles, Mac enrollment, capabilities, skills, hooks, curation, Telegram, workers, and trust boundaries. The docs split those flows into focused pages so you can start with the path that matches your machine and role.

Install and enroll Choose a role, set up a control host, enroll a Mac client, or ask a harness to install Brainstack safely. Local proof Run the disposable single-node smoke before committing to a daemon, Telegram bot, or tailnet setup. Capabilities Install local or worker-backed powers such as voice transcription without changing the harness surface. Skills and hooks Use public Brainstack skills, import shared skills, and keep harness context fresh in the background. Mac menu app Watch shared-brain health, proposals, Telegram routing, and fleet updates from the macOS menu bar. Proposals Turn raw evidence into scoped, reviewable memory and wiki proposals instead of unmanaged notes. Trust model See what can read, what can write, where tokens live, and how Brainstack behaves when offline.
Fastest proof: Install Brainstack on one private control host, enroll one Mac client, run brainctl doctor, then try one concrete capability such as local voice transcription. The docs walk through that path without crowding this page.

Bring existing context

Brainstack should start with what you already taught your tools

Cold-start memory is a product smell. Brainstack can plan imports from Codex skills, Claude and Cursor guidance, local markdown, and repo docs, then turn selected items into shared-brain imports or proposal-ready evidence.

brainctl import skills Scans current and default harness skill locations, prints a deterministic plan, and writes only when you add --apply.
brainctl import skill URL_OR_PATH Imports one skill from a local folder/file or source URL so connected harnesses can refresh it locally.
brainctl status --json Gives the Mac app and automation a bounded status surface for daemon, hooks, skills, proposals, and fleet freshness.
Next obvious product loop: A redacted shareable readiness report should package status, versions, hooks, capabilities, and proposal health for support or public setup wins without leaking tokens or private topology.

Features

The parts operators usually end up building by hand

⌕

Local search over the shared brain

Search uses derived local indexes, while markdown and artifacts remain reviewable in git.

⇵

Agent-friendly save path

Agents can save transcripts, notes, artifacts, and draft changes without pushing directly to the shared-brain repo.

▣

Quiet Telegram control plane

Short status, liveness, usage, and recap messages avoid accidental full-session resumes; file, machine, scheduling, and code work still take the durable path.

▣

Machine-to-Telegram file relay

Send yourself a PDF, log, image, or build artifact from an enrolled machine; the file streams through the control host's telemux path.

⚙

Deterministic runtime rendering

Generated runtime env files are separate from operator-owned secrets env files, and services run without ambient repo env files.

💻

Agent-ready runbooks

Codex gets installable Brainstack skills, while Claude and Cursor get concrete shared-brain guidance from checked-in templates.

✓

Doctor-first operations

Health checks report Bun, Git, SSH, Tailscale, harness paths, worker trust, services, and queued work.

Trust boundary

Private by default, explicit when it writes

The default Brainstack posture is one private network, one shared-brain repo, and clients that propose instead of mutating canon directly. The full trust model is in docs, but the pilot boundary should be clear before anyone installs it.

Read boundary Local clones and tailnet reachability define the normal read path. Do not expose braind to the public internet.
Write boundary Clients write imports and proposals. Admin tokens and direct wiki mutation stay with the control host or operator.
Hooks fail open If Brainstack is unavailable, harness hooks should return success and let Codex, Claude, Cursor, or the terminal continue.
Telegram is optional Telemux is a control surface, not the product. It should route supported operations to the same canonical brainctl paths.
Security docs: Read the trust model for tokens, prompt-injection posture, outbox behavior, Telegram risk, backup/restore, and uninstall expectations.
Brainstack architecture diagram showing agent tools, brainctl, braind, the shared-brain git repository, Telegram control, and private workers.
Simulated architecture view Private shared-brain architecture with optional Telegram control and tailnet workers.

Architecture diagram with agent tools on the left, brainctl and braind in the middle, the shared-brain git repository as the memory source, optional Telegram control, and private workers on the tailnet.

FAQ

Common questions

No. Brainstack gives those harnesses shared context, a write path, worker routing, and operational checks. The harness still does the reasoning and code work.
In a separate shared-brain git repo. Brainstack keeps product code and your memory data separate, then builds fast local search over that repo.
Yes. The local product smoke creates a disposable shared-brain repo under /tmp, runs doctor, and builds the search index without wiring Telegram, a worker, or Tailscale exposure.
Brainstack treats raw logs and remembers as evidence first. The curator promotes only scoped, intelligible proposals, so vague or stale notes do not silently become future prompt context.
Ordinary Mac clients can use a compiled brainctl binary with client bootstrap assets and public skills embedded, so they do not need Bun or a Brainstack source checkout. Control hosts and source-run workers still need Bun because they run Brainstack services from source.
Yes, if Codex has local machine permissions and you can provide the private invite for an existing Brainstack. It should ask whether the machine is a client, operator, control, or worker; check Git, SSH, Tailscale, and the selected harness; stop for missing Tailscale login or other prerequisites; enroll with --invite-file; then run brainctl doctor. It should not invent tokens, hostnames, or SSH pins.
The packaged skills are generic product runbooks: shared-brain usage, client discipline, operator checks, curation, worker ops, and file relay. Exact hostnames, Telegram routing, local paths, and personal topology belong in a private overlay skill.
No. The core shared-brain service and brainctl CLI work without telemux. Telegram is for operators who want phone-friendly control topics and scheduled routines.
Yes, when telemux is enabled and the invite includes the control-host SSH config. brainctl telegram send-file streams the file over SSH to the control host and lets telemux deliver it. The command rejects symlinks, oversized files, and sensitive-looking filenames unless you explicitly override the guard.
The default posture is private: loopback bind, trusted tailnet exposure, and operator-owned machines. Do not put it on the public internet unless you deliberately add the app-layer controls for that posture.

Get started

Bring one private machine and one shared-brain repo.

That is enough for the first pass: bring up one control host, connect the shared-brain repo, prove doctor is clean, then decide which Mac, Linux, Telegram, and worker surfaces are worth adding.

Talk about Brainstack Compare the suite