brain-ask

research-brain

🌐 Краткий старт по-русски — полная документация ведётся на английском.

🚀 New here? Start with FIRST-RUN.md — seven steps from an unpacked folder to your first digest (Windows is supported natively — .\install.ps1).

A distributable, configurable research workflow for people who follow more sources than they can read carefully. It helps select material worth attention, preserve source-backed concepts in a local Obsidian vault, and find those concepts again when a question returns. A weekly digest shows what changed and what may need review; it is one way to use the accumulated knowledge, not the knowledge base itself.

The workflow runs inside Cowork / Claude Code or another capable agent runtime. Its value over time still needs to be established in a real pilot, including the effort of checking and maintaining the notes.

It is topic-agnostic — point it at any subject by editing two config files.

---

Who it's for

The first supported audience is technical analysts, founders, researchers, and developers who already use an agent runtime and want a private, inspectable way to keep up with a fast-moving field, market, or set of sources. The agent does the collecting, distilling, and summarizing; you read the digest and explore the graph.

Two capability levels

The two modes share files, safety checks, and delivery state, but they are not feature-equivalent. If you want the compounding knowledge base described above, use the full agentic path.

Optional: query the vault from project agents

The experimental local MCP adapter lets another MCP-compatible agent search the vault index and curated concept text while you work in a project. It uses bounded lexical ranking over up to 1,000 notes / 32 MiB and returns at most two compact matches with excerpts and matching fields. It is not semantic search and does not build a generated index. With request_mode=research, it marks results as context for the existing local-corpus-first research workflow; the adapter itself does not run research. Saving requires an explicit user request and the interactive wiki-ingest approval gate. The adapter has its own isolated environment and does not add dependencies to the core runtime. Vault text returned through MCP may be sent to the connected host's configured model provider.

---

The 3-step pitch

1. Configure — open the folder in Cowork / Claude Code and say "let's set up sources". The setup-wizard skill interviews you and writes your config/.
2. Let it run — on a schedule (or on demand) the whole loop runs in order (weekly-run): collect → sanitize-incoming (the S1–S9 anti-injection gate) → pipeline-curate → weekly-synthesis (auto, into brain/) → extract lessons/playbooks → brain hygiene (validate_brain.py) → build digest → deliver. No manual step.
3. Read the digest — it lands in your enabled channels (email / Telegram / Rocket.Chat) with new sources, real concept definitions, and a one-line brain-health summary. The brain/ vault keeps growing underneath it.

---

Fastest start

Recommended full agentic path: unzip the archive, open the folder in Cowork / Claude Code, and say "let's set up sources". The setup wizard writes the config, then ends with an activation checklist (Source:, Config:, Delivery:, Schedule:, First value:, Next action:) from scripts/setup_check.py. Written files alone do not mean setup is complete; the schedule is only complete after you register one recurring run for schedule/weekly-run.md.

You can also acquire the source with git clone <repo-url> or download its ZIP. Use a separate unpacked copy for personal collection and delivery; contributor checks belong in the source checkout.

Advanced no-agent / RSS Digest Lite path: from inside the folder run:

./install.sh --configure

This bootstraps uv, creates .venv, seeds config/.env, and runs the terminal configurator for the reduced headless/RSS path. Use it when no agent runtime is available; the full compounding knowledge loop needs the full agentic path above. (A bare ./install.sh — what make install runs — installs the dependencies only and configures nothing.)

Full walkthrough (no terminal required): QUICKSTART.md. What compounds after a month vs an RSS reader — the week-1 → week-4 before/after: docs/WALKTHROUGH.md.

---

Features

• Weekly digest, the hero feature — a skimmable summary of new sources, real concept definitions, items needing attention, and a one-line brain-health note. It opens with a one-line volume summary and a TL;DR (busiest topic, standout source, every updated concept), groups new sources by topic badge (🏷) as a curated view — the top sources per topic by credibility with a +N more note and an optional one-line synthesis lead, not every article — shows updated concepts as cards with a per-concept publisher-diversity marker (🔵 / 🟡 — see below), a synthesis paragraph, and a "needs attention" backlog. It renders as plain text for Telegram and as a premium styled HTML email. Source-credibility (tier) markers, "quiet week" suppression, and idempotent delivery (per-channel receipts + a concurrency lock so overlapping runs can't double-send; re-runs skip already-sent channels unless --force) are built in. Full anatomy in USER_GUIDE.md / CONVENTIONS §17.
• Digest extras — glossary, daily & trends cadences, operator report — a plain-language 📖 Glossary section (terms from config/glossary.yaml) is appended when a digest uses jargon; an optional daily inflow digest (build_digest.py --daily) adds a second cadence; a weekly trends section rides every non-quiet weekly digest by default (--no-trends disables; standalone scripts/trends.py or /trends on demand); and build_digest.py --report writes a static browser operator report with a per-source audit drilldown — its Digest tab doubles as a morning reading list: a cross-topic Read today top-3 with reading estimates, momentum arrows on topic badges, per-source "why am I seeing this" chips, read-progress and ⭐ picks (shareable to Telegram), and a link back to the previous issue. See USER_GUIDE.md §5.
• Publisher-diversity markers — each concept can show how many publisher domains appear in its source records: 🔵 N retained publisher domains — check the claim or 🟡 One retained publisher domain — check the claim. Optional text deduplication can collapse near-identical reprints; it cannot prove independent reporting or that a passage supports a claim. The marker is a prompt to inspect the evidence, not a confirmation badge. See CONVENTIONS §16.
• Conversational setup — no hand-editing YAML; the setup-wizard writes the config for you. Starter-pack fast path, derives config/tags.yaml, asks per-source tier, writes the full schedule, explains each channel's prerequisites, and verifies activation with scripts/setup_check.py. It reports whether setup is complete, ready_schedule_not_registered, or `needs