npm package: @simbimbo/brainstem
Description: brAInstem — operational memory for weak signals.
Latest version: 0.0.17

# 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:

```bash
make bootstrap
source .venv/bin/activate
make test
```

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

```bash
make smoke
```

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

```bash
make runtime-check

# Equivalent npm path
npm run runtime:check
```

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

```bash
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:

```bash
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:

```bash
python -m brainstem.smoke
```

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

```bash
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`](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.