brAIn — Living Desktop Manager

A local-first research project exploring personal context learned over time:
a small spiking neural network, an inspectable dashboard, and an optional
context interface for AI assistants.

The long-term idea is a desktop companion that learns useful patterns and helps
at appropriate moments. The current repository is a research prototype, not a
validated emotion detector, autonomous desktop manager or production security boundary.

Get started · Documentation ·
Architecture · Roadmap ·
Privacy · Contributing

What works today

“Living” describes the research direction. DA, NE, ACh and 5HT are model
variables, not measurements of human neurotransmitters. Labels such as “flow”
are user-taught associations, not independently verified psychological states.
There is no demonstrated superiority to simple baselines or evidence of consciousness.

Quick start

1. Explore the dashboard without collecting data

Python 3 is sufficient for the static dashboard; no model or sensor permissions:

git clone https://github.com/Triponymous/brAIn.git
cd brAIn
python3 -m http.server 4178 --bind 127.0.0.1 --directory docs/dashboard-concepts

Open Observatory.
Choose Introduction for the guided tour. English is the default; Deutsch
remains available, including during a tour. The chosen language is stored locally.

Loading the page does not enable capture. If an observation runner is already
running, the dashboard can display its existing capture status; closing a tab
does not stop that runner.

2. Install the research environment

The package declares Python 3.11 or 3.12. Real desktop sensors target macOS;
mock/offline tests do not establish cross-platform sensor support.

uv venv --python 3.12
uv pip install -e ".[dev]"
uv pip check

Dependency constraints are in pyproject.toml, including
torch>=2.13. Do not silently lower that requirement to make installation pass.
A fresh installation with the current constraints has not been verified in this
documentation update; see verification notes.

3. Optionally observe real model steps

In a second terminal, from the repository root:

.venv/bin/python -m server.observe --desktop-metadata

Open Live session → Data & privacy. All four sources begin off in a new
runner session. Enable only sources you want, then use Connect local model.

• Stop all capture stops source queries and subsequent model steps.
• Disconnect view or freezing the timeline does not stop capture.
• Ctrl-C stops the observation runner.
• No checkpoint is loaded or saved. Exports remain your responsibility.

Without --desktop-metadata, the runner provides connection/status inspection
but does not allow sources to be enabled. See runtime guide
and capture details.

Persistent research and AI context

For persistent learning, use the separate training console and daemon described
in Running brAIn. Review privacy boundaries
before starting: this path includes microphone features, app metadata, disk
persistence, chat and optional voice/cloud functionality.

The brain-mcp executable exposes nine query tools from that daemon:
state, history, concepts, learned labels, habits, anomalies, explanations,
recall and experience summaries. It does not connect to Observatory's
port-8001 observation model.

See MCP interface for transport, tools and disclosure limits.
A compatible host may use these tools to ground responses. This does not train
frontier-model weights or guarantee support in every ChatGPT/Claude application.
Client-specific setup and a reusable integration skill remain separate concerns.

Architecture

The default Brain() contains 200 sensory, 500 expansion, 200 concept and
100 working-memory units. Expansion outputs are binary projections, not LIF
membranes. Restored checkpoints may have different dimensions; the runtime's
exported architecture is authoritative, not unused configuration fields.

Desktop inputs → encoding → SNN + concept tracking
                              ├─ observe → Observatory Live session (ephemeral)
                              └─ braind → checkpoint + logs + learned labels
                                            ├─ training console
                                            ├─ optional LLM/voice/capabilities
                                            └─ query API → stdio MCP → chosen client

These are separate runtime paths, not two views of one shared model.
The anatomical 3D asset is a visual reference: computational role placement is
illustrative and live synaptic connections are not exported.
Architecture and limits.

Research priorities

1. Reproducible sessions, explicit consent and a complete data lifecycle.
2. Personal adaptation evaluated against simple rules and classical baselines.
3. A permission-scoped context interface with freshness, provenance and revocation.
4. Offline VAD and sparse-circuit ablations before live integration.
5. Optional wearables, interruption policies and resumption cards only after
   their incremental value can be tested.

These are proposed milestones, not shipped features or promised dates.
Roadmap and acceptance criteria.

Contributing and verification

See CONTRIBUTING.md for safe tests, branch conventions and PR
expectations. Existing benchmark scripts are research diagnostics; historical
synthetic scores are not validated stress detection, battery savings or
longitudinal user outcomes. Current verification scope.

The former Tauri pet-face/ application has been removed. Voice backend code
still exists; there is no current Pet-Face build target. A hardware companion
and wearable integrations are proposals, not supported products.

Author and license

Created by Leon Matthies (Triponymous), an independent research project.

Code: MIT. The derived anatomical asset is separately licensed under
CC BY-SA 4.0, with required attribution in
brain-LICENSE.md.
Bundled Three.js retains its MIT notice.
Do not treat the whole repository's media as MIT or upload personal observations.