brAInstem

Operational memory for weak signals

brAInstem is a local operational memory runtime for weak‑signal detection. It treats logs and events as raw operational experience, normalizes them into a canonical stream, assigns attention, and emits compact operator‑facing summaries.

What it does today

• Ingests syslog, file, LogicMonitor‑shaped payloads, and uploads into raw envelopes
• Canonicalizes events, assigns attention, and generates weak‑signal candidates
• Exposes a compact operator digest with health + posture summaries
• Preserves raw/canonical lineage for investigation and replay

Why operators use it

Most operational pain never becomes a classic threshold alert. It shows up as:

• recurring low‑grade warnings
• brief self‑healing failures
• cross‑system weak signals
• near‑misses that humans forget because there is too much noise

Traditional monitoring catches hard failures. brAInstem fills the gap by surfacing patterns that are real but easy to miss.

How it works (current behavior)

Logs and events are:

1. ingested into a provenance‑preserving raw envelope
2. normalized into one canonical event stream
3. assigned and updated with attention over time
4. compressed so most inconsequential noise is handled cheaply
5. promoted into operator‑facing weak‑signal outputs only when enough attention is earned
6. retained for lookup when similar patterns recur

Primary users

• MSP owners
• MSP technicians
• NOC teams
• SRE / infrastructure operators
• small security / ops teams dealing with alert fatigue and log blindness

Local bootstrap and test workflow

Use this canonical path for a known-good local setup:

make bootstrap
source .venv/bin/activate
make test

Optional smoke check (compact import/config/API surface self-check):

make smoke

Runtime/deployment check (focused API/digest/upload/runtime sweep):

make runtime-check

# Equivalent npm path
npm run runtime:check

Release prep helper (updates repo version metadata in one shot):

make prepare-release VERSION=0.0.17

# Or directly
python3 scripts/prepare-release.py 0.0.17

This updates:

• package.json
• pyproject.toml
• brainstem/__init__.py
• top CHANGELOG.md release heading

Release check (before publish)

Run this before pushing a release so metadata stays aligned:

make release-check

# Equivalent npm path
npm run release:check

This validates that:

• package.json version
• pyproject.toml version
• brainstem.__version__
• changelog top heading version in CHANGELOG.md

and runs a full pytest suite.

You can also run the same check directly when debugging source-only workflows:

python -m brainstem.smoke

If you prefer not to use make, the explicit equivalent is:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
python -m pip install -e ".[dev]" || python -m pip install ".[dev]"
pytest

Operator questions it answers today

For a given tenant or environment, brAInstem answers:

• What happened today that mattered but never alerted?
• What self-resolving issues are recurring?
• What patterns are likely to become tickets later?
• Have we seen this before?
• What happened right before the last similar incident?

Current implemented runtime surface

Current implementation is intentionally bounded:

• FastAPI runtime at brainstem.api:app
• Implemented API endpoints include:
• POST /ingest/event, POST /ingest/batch, POST /ingest/logicmonitor, POST /ingest/upload, POST /replay/raw, POST /ingest/spool/replay
  • POST /rebuild/derived, POST /snapshot, POST /storage/clear
• POST /maintenance/replay, POST /maintenance/spool/replay, POST /maintenance/rebuild, POST /maintenance/snapshot, POST /maintenance/clear
  • GET /interesting, GET /candidates, GET /signatures, GET /recurrence_analysis, GET /canonical_events
  • GET /stats, GET /failures, GET /failures/{id}
• GET /raw_envelopes, GET /ingest/recent, GET /ingest/spool, GET /operator_digest, GET /sources, GET /sources/status
  • GET /runtime, GET /runtime/sources, GET /maintenance/actions/recent, GET /status, GET /healthz
• UDP syslog listener at brainstem.listener
• source-driver intake for syslog, file, and narrow logicmonitor connector payload shape
• SQLite-backed persistence with default DB at .brainstem-state/brainstem.sqlite3
• optional API token in BRAINSTEM_API_TOKEN

Runtime config can also be inspected at /runtime. The runtime summary now includes explicit source_capabilities (source_types + per-source ingest-mode descriptors with maturity/notes) and auth/capabilities flags.

Quick run path (API + listener + file/syslog intake)

See the compact run surface in:

• docs/README.md

Preferred operator launch path now includes:

• make run-api
• make run-listener
• make smoke

It covers API startup, listener ingest, and file ingest end-to-end with only implemented entry points and current payload shapes.

Relationship to ocmemog

Shared DNA:

• ingest -> candidate -> promotion pipeline
• compact retrieval
• provenance and explainability
• memory scoring and recurrence awareness

Different center of gravity:

• ocmemog = assistant memory and continuity
• brAInstem = operational event intelligence and weak-signal detection

Initial scope

The long-term product direction is an always-on self-contained runtime with a robust input apparatus, a discovery apparatus, and operator-facing outputs.

For the first public prototype line, start with:

• a narrow but real ingestion story
• a canonical event stream
• attention-oriented weak-signal discovery
• operator-facing interesting items / digest output
• syslog-like events and LogicMonitor-shaped events as early proof sources

Delay until later:

• broad universal connector coverage
• mature syslog appliance behavior across every input mode
• full SIEM behavior
• broad compliance workflows
• generic observability replacement
• "chat with all your logs" as the primary story

Proposed docs

• docs/design-governance.md — canonical product/design guardrails
• docs/v0.0.1.md — first release scope and acceptance criteria
• docs/adapters.md — intake, raw envelope, and canonical event contract
• docs/vision.md
• docs/architecture.md
• docs/scoring.md — attention scoring and routing model
• docs/roadmap.md — compact product completion checklist and near-term roadmap

Design governance

Before expanding scope, adding connectors, or making architecture claims, read:

• docs/design-governance.md

That document is the canonical governor for:

• what brAInstem is and is not
• how attention should work
• what belongs in 0.0.1
• how the input apparatus, discovery apparatus, and operator outputs should evolve

Build execution plan

For the current implementation sequence, near-term gap list, and ordered next milestones, use:

• docs/build-plan.md

That is the canonical execution sheet for what is done, what remains, and what should be built next.