Integration kit · astra-2cerebro
The second brain outside the terminal
Connects your Markdown folder to a Telegram bot, a site via a local API, databases and spreadsheets, n8n, and voice. Node.js, zero dependencies.
Connects your Markdown folder to a Telegram bot, a site via a local API, databases and spreadsheets, n8n, and voice. Node.js, zero dependencies.
The brain created by astra-2cerebro works very well in the terminal. But the question comes in through Telegram, the site needs the catalog in the wiki, and the database generates records every night. cerebro-integra is the layer that translates each channel into safe reads and writes to the brain's files.
Local HTTP API, Telegram bot, importers (JSON, CSV, folder, wiki export), n8n workflow, and voice bridge. They all communicate with a single core, lib/cerebro.mjs.
API only on 127.0.0.1, optional token, writing disabled until you turn it on, Telegram chats on an allowlist, path traversal blocked, token never printed.
Only node:http, fetch e fs. Without npm install. Clone, copy the .env, runs. 73 tests with node --test.
No adapter touches files directly. The core knows where everything lives in the brain (fontes/, decisoes/registro.md, rotinas/registro.md, wiki/) and only writes by appending: nothing is overwritten.
GET /buscar, /contexto, /prioridades, /pagina, /projetos, /conexoes. Accent-insensitive search, all terms required, title bonus.
POST /decisao, /fonte, /rotina/execucao and the commands /decisao, /fonte, /rotina from the bot. Only with CEREBRO_ESCRITA=1.
One note per item in fontes/AAAA-MM-DD-slug.md. Deterministic name: running it every night doesn't create duplicates. Date comes from the item or the file, never from "today".
The bot needs a BotFather token; voice needs the STT/TTS commands you choose. Nothing is installed by you besides Node.
If you use Claude Code or Codex, you already have it.
node --version # v20 or higher
Folder with AGENTS.md/CLAUDE.md, contexto/ e fontes/, created by astra-2cerebro. To try it, test/fixture/ is a minimal brain.
ls ~/meu-cerebro # AGENTS.md context/ sources/ wiki/ ...
On Telegram, @BotFather → /newbot. Store the token in .env. Find your chat ID with getUpdates.
# .env TELEGRAM_TOKEN=123456:ABC... TELEGRAM_CHATS=123456789
All commands are real and available in the repository. The full documentation (API route by route, Telegram, importers, n8n, voice, security, and three recipes) is in docs/.
Without npm install. O .env is read from the current folder without overwriting variables that are already set.
git clone https://github.com/inematds/cerebro-integra.git cd cerebro-integra cp .env.exemplo .env # edit CEREBRO_DIR=/caminho/para/meu-cerebro npm test # 73 tests, uses a copy of test/fixture/, doesn't touch your brain
Listens only on 127.0.0.1:4650. With CEREBRO_TOKEN, every route (except /saude) requires Authorization: Bearer.
npm run api # [api] brain: /home/usuario/meu-cerebro # [api] listening at http://127.0.0.1:4650 # [api] token: required · writing: off · cors: off curl 'http://127.0.0.1:4650/buscar?q=catalogo&limite=3' -H "Authorization: Bearer $CEREBRO_TOKEN" curl http://127.0.0.1:4650/prioridades -H "Authorization: Bearer $CEREBRO_TOKEN"
By default, the API and bot only read. Writing always means appending: existing sources are not overwritten, records only gain lines.
CEREBRO_ESCRITA=1 npm run api curl -X POST http://127.0.0.1:4650/decisao -H "Authorization: Bearer $CEREBRO_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"titulo":"Usar a API no site","decisao":"O site consulta /buscar.","porque":"Uma fonte só."}' # → appends "## 2026-09-07: Use the API on the site" to decisoes/registro.md
Long polling: no open port, no HTTPS. Only responds to chats in TELEGRAM_CHATS; without the list, it won't start.
npm run bot # [bot] @meu_cerebro_bot · brain: /home/usuario/meu-cerebro # [bot] allowed chats: 1 · writing: off · reply: search # in chat: /buscar catálogo prazo /prioridades /decisao Usar API | O site consulta a API | Uma fonte só /rotina importar-catalogo ok 12 notas # forwarding any message to the bot saves a note in sources/
With RESPONDER_CMD, the bot and voice run the command in the brain folder with the question as standard input. Without it, free text returns search results.
# .env RESPONDER_CMD=claude -p # runs in CEREBRO_DIR, reads CLAUDE.md automatically
Field map in JSON. --simular lists what would be created. Running it again skips what already exists.
# mapas/catalogo.json { "titulo": "nome", "data": "criado_em", "id": "sku", "prefixo": "catalogo", "corpo": ["descricao"], "tags": "categorias", "extras": ["preco"] } node importadores/importar-json.mjs catalogo.json --config mapas/catalogo.json --simular node importadores/importar-json.mjs catalogo.json --config mapas/catalogo.json # created: 340 · skipped (already existed): 0 node importadores/importar-csv.mjs produtos.csv --config mapas/catalogo.json node importadores/importar-pasta.mjs ~/Documentos/notas --prefixo notas
A JSON file with pages, frontmatter, and links [[slug]], broken links, and orphan pages. Useful for external search, a static site, or a dashboard.
node importadores/exportar-wiki.mjs --saida wiki.json # exported: 4 pages, 8 links → wiki.json
Import n8n/fluxo-exemplo.json (webhook → /buscar → reply; token via $env). Voice is a bridge via environment variables, with --texto to test without a microphone.
TTS_CMD='espeak-ng -v pt-br --stdin' voz/voz.sh --texto "o que sabemos sobre o catálogo" # [voice] question: what do we know about the catalog # Found 3 results. 1. Phase 2 kickoff meeting. ... GRAVAR_CMD='arecord -d 6 -f cd -q' STT_CMD='whisper-cli -nt -f' voz/voz.sh
Cron → importer → POST /rotina/execucao. The entry goes at the top of "Execution log" in rotinas/registro.md: that's what the /auditar the kit searches. Full recipe in docs/receitas.md.
# crontab 0 23 * * * /home/usuario/cerebro-integra/rotinas/importar-catalogo.sh >> ~/logs/importar.log 2>&1 # at the end of the script: curl -X POST http://127.0.0.1:4650/rotina/execucao -H "Authorization: Bearer $CEREBRO_TOKEN" \ -H 'Content-Type: application/json' -d '{"id":"importar-catalogo","resultado":"ok","saida":"12 notas novas"}'
Real outputs, generated from the example brain in test/fixture/.
{
"consulta": "catalogo",
"total": 2,
"resultados": [
{ "caminho": "contexto/sobre-o-trabalho.md",
"titulo": "Sobre o trabalho", "pontos": 4,
"trecho": "...um catálogo de produtos artesanais..." },
{ "caminho": "fontes/2026-08-18-reuniao-kickoff-fase-2.md",
"titulo": "Reunião de kickoff da fase 2", "pontos": 4,
"trecho": "...cobre o catálogo de produtos..." }
]
}you: /prioridades bot: Priorities: 1. Deliver phase 2 of [[projeto-alfa]] by the end of the quarter. 2. Organize [[empresa-x]]'s product catalog in a searchable database. 3. Reduce customer response time to less than one business day. you: /rotina importar-catalogo ok 12 notas novas bot: Execution recorded: importar-catalogo · ok · 2026-09-07 23:00 you: /decisao a | b bot: Writing is disabled. Start the bot with CEREBRO_ESCRITA=1 to record.
| Route | Does | Requires |
|---|---|---|
GET /saude | version, brain, flags, route list | none (open for monitoring) |
GET /contexto · /prioridades | about-me, work, priorities, route map | token, if configured |
GET /buscar?q=&limite=&pasta= | searches all .md/.txt files | token |
GET /pagina?caminho= | one file, with frontmatter; blocks traversal | token |
GET /projetos · /conexoes · /rotinas | kit tables as JSON | token |
POST /decisao · /fonte · /rotina/execucao | attaches to decisoes/, fontes/, rotinas/ | token + CEREBRO_ESCRITA=1 |
Version 1.0.0 covers all five channels. The next ideas are small and will only be added when someone actually needs them.