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
| Component | Implemented | Important boundary |
|---|---|---|
| SNN core | PyTorch LIF steps, fixed expansion, STDP/BCM, competitive concepts, working memory and model modulators | Online learning is implemented; real-world usefulness still needs controlled evaluation |
| Observatory | Interactive 3D atlas, Circuit view, inspectors, timelines and an 18-step English/German introduction | Five pages use synthetic demonstration data; only Live session reads observed model steps, from the persistent daemon or a session runner |
| Opt-in observation | Four individually switchable desktop-metadata sources, stop control, captured frames and JSON export | Separate fresh model; no persisted checkpoint, microphone, LLM or wearable access |
| Research daemon | Persistent model, learned labels, episode/experience logs and optional LLM/voice paths; started, shared and watched in Observatory's Live session | Broader data access than the session runner: five sources, each off until shared under Live session → Persistent brain; the runner's four switches do not control it |
| MCP context interface | Nine query tools over stdio, backed by the daemon | Reads can expose personal metadata to the client and are logged locally |
| Audio experiment | Offline Mel/RMS versus Mel/RMS + VAD evaluation pipeline | No established improvement on real recordings; not integrated into live capture |
“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.
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-conceptsOpen 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 the daemon or an observation runner is already running, Live session shows its existing capture status; closing a tab stops neither.
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 checkDependency constraints are in pyproject.toml, including
torch>=2.13. Do not silently lower that requirement to make installation pass.
A separate macOS/Python 3.11 environment with PyTorch 2.13.0 was installed and
dependency-checked on 2026-09-17; see verification scope.
In a second terminal, from the repository root:
.venv/bin/python -m server.observe --desktop-metadataOpen Live session, choose Session runner, then 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.
For persistent learning, run .venv/bin/python -m server.control and open the
dashboard it serves at http://127.0.0.1:8900. Live session → Persistent brain
starts and stops the daemon, shares its sources one by one, shows its actual
model steps and lets you name moments; see Running brAIn. Review privacy boundaries
before sharing sources: once switched on, this path can include microphone
features and app metadata, plus disk persistence, chat and optional voice/cloud
functionality. The daemon captures nothing until a source is shared.
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.
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
├─ Observatory Live session (sources, steps, words)
├─ optional LLM/voice/capabilities
└─ query API → stdio MCP → chosen client
These are separate runtime paths, not two views of one shared model; Live session shows one of them at a time. The anatomical 3D asset is a visual reference: computational role placement is illustrative and live synaptic connections are not exported. Architecture and limits.
- Reproducible sessions, explicit consent and a complete data lifecycle.
- Personal adaptation evaluated against simple rules and classical baselines.
- A permission-scoped context interface with freshness, provenance and revocation.
- Offline VAD and sparse-circuit ablations before live integration.
- 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.
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.
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.