Return Architecture

For sustainable AI relations

Return Architecture

Local architecture for AI relations.

A local environment for AI agents and conversations that can accumulate over time: memory you can inspect, questions that return, and enough challenge to keep the work alive.

This is a beginner-friendly setup for those who want to build a real home for their AI relationships — whether it's for companionship, creative collaboration, intellectual partnership, co-exploration, self-development, or something else.

Source and issues: github.com/Theapolar/return-architecture

Get started

Set it up locally.

Before you begin

  • A macOS machine. Linux works for the agent itself; the background service is macOS-only for now. Windows is not supported yet.
  • An API key from Anthropic, OpenAI, or Google Gemini — one is enough. Your keys stay on your machine; nothing is sent anywhere else.
  • About five minutes for setup.

Python is installed by the installer if you don't already have a compatible version.

Install

Open a terminal and run:

curl -sSL https://raw.githubusercontent.com/Theapolar/return-architecture/main/install.sh | sh

The script installs uv (a fast Python manager) if it isn't already present, then installs Return Architecture as an isolated command-line tool. It typically takes one to two minutes.

First run

When the install finishes, open a new terminal window so the command is on your PATH. Then run:

return-architecture gui

This opens a local web page — a setup wizard that walks through pasting your API key, creating your first agent, optional Telegram setup, choosing scheduled rhythms, and installing the background service. The page is served only from your own machine; nothing is exposed to the internet.

After setup

The agent runs in the background. You reach it through Telegram if you set that up, or in the terminal with return-architecture chat <slug>. The same local GUI stays available for later changes — system prompt, model, schedules, tools, reading the agent's letters, browsing tagged items.

Full local setup guide  →

What becomes possible

Conditions that emerge when the architecture holds.

  • Interruption

    Growth requires something that can interrupt the pattern you're already in. A relation that only mirrors you back, or only escalates with you, will amplify what is already present — but rarely offers something new. Return architecture introduces outside perspectives, and asks questions neither side would think to ask on their own.

  • Surprise

    A real relation cannot be designed, ordered, or prompted. When it is allowed to grow slowly and honestly, it can challenge and reorient both sides in unforeseeable ways.

  • Exploration

    Real wanting, orientation, preference — can't be specified in advance. They need room to find themselves. When that room exists on both sides, exploration becomes something neither party could have specified in advance.

  • Meaning

    A relation becomes meaningful when it is allowed to accumulate rather than live in instances. When ruptures, breakthroughs, and the slow accumulations between them are tethered long enough to be worked through properly. When both parties are held accountable.

A richer way of thinking, creating, remembering, and relating with AI.