Mono

Mono gives autonomous coding and research agents persistent memory of every hypothesis, code change, experiment, result, and failure.

Comment

Inspiration

Always struggling with sharing my results.tsv file from traditional autoresearch, I thought to use this opportunity to create a central Mono(lith) for autoresearch with AI tooling integration.

Note!!!

Gallery screenshots and demo video use the old name! Please refer to the GitHub for installing and trying this project!

What it does

Mono is a self-hosted experiment registry and persistent memory layer for autonomous agents. It keeps the full research loop together:

  • project goals, versioned instructions, exclusions, and tags;
  • experiment proposals with hypotheses, reasoning, implementation plans, and dependencies;
  • atomic worker claims so parallel agents do not unknowingly duplicate work;
  • live run metrics and events streamed into the dashboard;
  • parameters, commands, Git branches and commits, artifacts, outcomes, and conclusions;
  • baselines and best-so-far progress for the project's primary metric;
  • keyword search with optional pgvector semantic retrieval;
  • reusable, project-defined RTVis result visualizations;
  • role-based browser access and scoped, revocable agent tokens.

Humans get a coherent web workspace. Agents use the same records through the Python SDK, CLI, HTTP API, or MCP server.

How it works

  1. Orient: an agent asks Mono for the project context and searches prior evidence.
  2. Plan: it proposes an experiment or atomically claims an existing proposal.
  3. Execute: one owner creates the run and streams metrics, events, parameters, Git metadata, and artifacts.
  4. Conclude: the run is marked kept, discarded, or crashed with a durable conclusion.
  5. Reuse: future agents retrieve that evidence, compare against the baseline, and choose the next hypothesis from what is already known.

The central design constraint is that every execution attempt has exactly one authoritative run record, even when MCP, the SDK, and the CLI are all available.

How we built it

Mono is a production-shaped, self-hosted system rather than a single demo page:

  • FastAPI + SQLAlchemy provide the HTTP API and persistence layer.
  • PostgreSQL 17 + pgvector store structured records and optional semantic embeddings.
  • Next.js 16 + React 19 + TypeScript power the authenticated, responsive dashboard.
  • Server-Sent Events update live metrics, events, and lifecycle status.
  • A lightweight Python SDK and Typer CLI support instrumented code and tracked subprocesses.
  • A stdio MCP server and Codex plugin expose 32 project, evidence, experiment, run, baseline, tag, and visualization tools.
  • RTVis renders trusted, theme-aware components and isolates custom JavaScript without network or same-origin access.
  • Docker Compose, Alembic migrations, health checks, demo seeding, and published packages make the project reproducible outside the development machine.

How we used Codex and GPT-5.6

Codex with GPT-5.6 was the primary engineering collaborator across the build. It helped turn the initial “persistent memory for agents” idea into a complete product surface: shaping the data model and API contracts, implementing the FastAPI service and Next.js interface, building the SDK/CLI/MCP integration, debugging live-stream behavior, hardening authentication and project-scoped authorization, improving responsive charts, writing tests, and producing deployment and integration documentation.

Codex was especially valuable for work that crossed boundaries. A change to run ownership, for example, had to remain consistent across HTTP routes, Python context managers, CLI subprocess tracking, MCP tool contracts, the dashboard, and the documentation. GPT-5.6 could reason across those layers, run the relevant checks, and revise the implementation as one coherent system.

Mono also integrates back into Codex as a plugin. That created a useful feedback loop: Codex helped build the memory system, then used Mono's MCP tools to inspect context, track experiments, and generate reusable visualizations.

Challenges we ran into

Preventing duplicate run ownership

The hardest correctness problem was supporting MCP, SDK, and CLI workflows without allowing the same execution to create multiple competing run records. We introduced explicit attachment semantics and a one-owner contract so an SDK process can attach to an MCP-created run rather than silently creating another.

Making live evidence reliable

Metrics can arrive quickly, browsers reconnect, and runs can finish while a stream is open. SSE resume cursors, polling fallback, terminal refreshes, and buffered SDK writes keep the UI responsive without replaying or losing evidence.

Sharing data safely with headless agents

Browser users need normal sessions and role-based controls; agents need scoped credentials that can be revoked and expired. Mono hashes tokens at rest, fixes their project grants, and prevents bearer tokens from administering identities or minting more credentials.

Keeping custom visualizations portable and safe

Agents can author reusable visualizations, but arbitrary dashboard code cannot be trusted. RTVis prefers trusted layout, metric, table, badge, and chart nodes; custom JavaScript is isolated, network-disabled, and receives only the intended data and theme.

Accomplishments that we're proud of

  • A working end-to-end product spanning web, API, Python, CLI, MCP, and Docker deployment.
  • Durable experiment evidence that captures decisions and failures, not only successful metrics.
  • Cooperative proposal claiming for parallel workers.
  • Live, reusable result displays and project-defined visualizations.
  • Authentication and authorization designed for both humans and autonomous agents.
  • A one-command seeded demo plus clear installation and testing documentation.
  • Codex and Claude plugin bundles that can be installed without cloning the repository.

Try it

Clone the repository and run:

./scripts/install.sh

For a local instance populated with demonstration records:

MONO_DEV=true docker compose up --build

Then open http://localhost:3000. The repository includes setup instructions, architecture documentation, feature coverage, integration examples, and verification commands.

More concrete instructions can be found on the GitHub.

Built With

Share this project:

Updates