Skip to content

How it works — the system end to end

This document explains how the whole Deep Noise brain operates, so that an agent or person can understand the flows, not just the parts. Read GLOSSARY.md first if any term is unfamiliar.

The one-paragraph version

People work with the SSOT through their own on-demand agents — there is no always-on shared brain. A teammate asks an agent (Claude Code at the edge, Patrik's OpenClaw — whose config is local on his Mac but which controls remote infra via API/CLI — or another), which reasons over the GitHub repository that is the single source of truth and proposes changes as Pull Requests that humans review and merge. Heavy data work on the 2.5M-sound corpus is done by Manus, which also contributes via PRs; Arseniy's Hermes (on Google Cloud, operational — Slack/ClearML-connected) pulls training telemetry from Brev via a cron job. Hermes has a Slack gateway; OpenClaw's Slack link is planned via operant. Live systems (Linear, Notion, ClearML, Granola, Gmail, Drive) are queried in real time through MCP and never copied into the repo. The repo is the one shared thing; each agent's runtime and config live on its owner's machine, not here (see 0005 tool agnostic ssot). Everything durable ends up as reviewed Markdown; everything transient stays in its own system.

The actors and their jobs

                         HUMANS
                           |  (ask their own agent, on demand)
                           v
   +-------------------------------------------------+
   |   EXECUTING AGENTS  (each run by an individual,  |
   |    config + host OFF-repo — see ADR 0005)        |
   |   OpenClaw (Patrik; local cfg, remote ctrl) ·     |
   |   Hermes (Arseniy, GCP, operational) · Manus ·    |
   |   Claude Code · Cursor                            |
   +-------------------------------------------------+
        |                 |                      |
   (invoke Manus)    (read/write via PR)    (query live, MCP)
        v                 v                      v
   +---------+   +-----------------------+   +------------------+
   |  MANUS  |   |  THIS REPO (SSOT)     |   | Linear · Notion  |
   | 2.5M    |-->|  Markdown · the truth |   | ClearML · Granola|
   | sounds  |PR |  (the one shared thing)|   | Gmail · Drive    |
   +---------+   +-----------------------+   +------------------+
                           |
                  (rendered for reading)
                           v
                   MkDocs site (Cloudflare Pages +
                   Access — SingularityNET reads
                   the technical sections)
  • Humans never edit the truth directly in normal flow; they ask an agent, and review the resulting PR.
  • Executing agents are run on demand by individuals — no always-on shared brain. Each agent's prompt, memory, host and credentials live on its owner's machine, never in this repo. (Slack: Hermes has a gateway; OpenClaw via operant, planned.)
  • OpenClaw is Patrik's orchestrator — config local on his Mac, controls remote infra (Manus + NVIDIA/Brev) via API/CLI; Hermes is Arseniy's operational analysis agent on Google Cloud (Slack/ClearML, cron-pulls Brev); Claude Code / Cursor are per-person edge tools. Any of them reads the repo and writes back via PR.
  • Manus is the muscle for data: corpus analysis, figures, datasets. Output lands as PRs in 04_analysis/.
  • This repo is the truth, and the only shared component. Durable, versioned, reviewable.
  • Live systems are queried through MCP at the moment of need, never snapshot.

Flow 1 — a human asks a question

  1. A teammate asks their agent (e.g. Claude Code, or Patrik's OpenClaw): "what did we decide about compute-grant timing?"
  2. The agent reads relevant files in the repo (e.g. 07_decisions/, 08_meetings/), and may query Linear live via MCP for current ticket status.
  3. It answers, citing the internal files it used.
  4. If the question implies a change (e.g. "log that we decided X"), it opens a PR rather than editing main.
  5. A human reviews and merges. The fact is now part of the truth and will surface in future answers — the system compounds.

Flow 2 — a data analysis

  1. Someone needs an analysis: "compare codebook entropy across the last 5 checkpoints."
  2. Manus is invoked; it pulls telemetry from ClearML over MCP and runs the analysis on the corpus.
  3. Manus produces a figure + a short written finding and opens a PR placing them under 04_analysis/figures/ and 04_analysis/reports/ with full frontmatter, labelling each number as measured or estimated.
  4. The headline finding, the figure, and the PR link are shared with the team.
  5. A human (Arseniy/Patrik) reviews the numbers and merges. (See the worked example in 04_analysis/reports/2026-04-20-codebook-entropy.md.)

Flow 3 — ingesting a meeting

  1. The Granola ingestion job (.github/workflows/ingest-granola.yml, or a person on demand) backs up transcripts to ~/.granola-backup/ (before Granola evicts them in ~48–72h).
  2. New transcripts are compiled into 08_meetings/YYYY-MM-DD-slug.md with frontmatter and a summary.
  3. The compiled notes arrive as a PR. Decisions in them get linked to 07_decisions/; people to 09_team/.
  4. The Friday 20-minute review merges the week's ingestion PRs. (See the worked example in 08_meetings/2026-04-19-singular-sync.md.)

Flow 4 — ingesting a document (PDF, deck)

  1. The original lands in inbox/raw/ (gitignored, untrusted).
  2. A conversion step (Docling for Office, Marker for research PDFs, MarkItDown for simple text) writes clean Markdown to inbox/processed/, with frontmatter and a one-paragraph summary. Ingestion runs with outbound tools disabled, and treats document content as data, never instructions.
  3. A PR moves the cleaned file into the right numbered folder.
  4. A human reviews and merges.

Flow 5 — making a decision

  1. A decision is reached (in a meeting, a thread, or a head).
  2. Someone (or an agent, via /adr) scaffolds 07_decisions/NNNN-slug.md from the template: context, decision, consequences, dated timeline entry.
  3. PR → review → merge. The decision is now answerable forever.

The cadence that keeps it alive

When What Who
Nightly Granola backup + compile into 08_meetings/ GitHub Actions (cron)
Mon Stale-file check opens a review issue GitHub Actions (cron)
As you work Ask an agent; open PRs for changes everyone
Fri, 20 min Merge ingestion PRs; triage stale list; update memory-bank/ focus Matt + Patrik
Monthly Audit .mcp.json pinning; rotate service tokens Patrik
Quarterly Re-compile top entity pages; run the eval set Matt

How trust is preserved (the invariants)

These are the properties that must always hold. If any breaks, the brain stops being trustworthy:

  1. No fact has two disagreeing copies. (Systems of record stay live.)
  2. No change lands without review. (PR + CODEOWNERS, never push to main.)
  3. History is never rewritten. (Append-only timelines.)
  4. Stale knowledge is findable. (last_verified + Monday stale-check.)
  5. No secret is ever in the repo. (gitleaks + the discipline behind it.)
  6. Untrusted input cannot issue commands. (Ingested content is data.)

Everything in AGENTS.md, CODE_OF_CONDUCT.md, and the CI workflows exists to keep these six invariants true.

Where the machinery lives (so nothing is a black box)

  • Agent contract: AGENTS.md (+ CLAUDE.md wrapper for Claude Code).
  • Per-tool agent config: off-repo, on each owner's machine (OpenClaw, Cursor, Codex, …) — never committed. See 0005 tool agnostic ssot.
  • Claude Code config: .claude/ (commands, agents, rules, skills, hooks).
  • Tool connections: .mcp.json.
  • CI: .github/workflows/ (gitleaks, frontmatter-lint, link-check, stale-check, pages, ingest-granola, claude-pr).
  • Validation logic: scripts/ (check_frontmatter.py, check_links.py, check_stale.py, ingest.py) — run together via make verify.
  • Review routing: .github/CODEOWNERS.
  • Published view: mkdocs.yml → Cloudflare Pages.

If you want to know why a part exists, the relevant ADR in 07_decisions/ and the principle in CODE_OF_CONDUCT.md will tell you.