Tech0001/orrery

Persistent memory for coding agents, across sessions, models, tools and machines.
A coding agent forgets everything when its session ends, and a long project outgrows any one conversation. Orrery
gives each of your agents a lasting memory: every message it has seen, plus a tree of summaries over them. The agent
works from a compact view of its whole history and can look up the original messages whenever it needs them.
The memory belongs to the agent, not to a session, a folder or a tool. Start a fresh session, change models, move
from pi to Claude Code, open the agent in another project or carry on from another computer, and it still remembers.
What you can do
- **Keep one agent across tools.** pi, OMP (oh-my-pi) and Claude Code all read and record the same agent's memory.
OpenRouter's Ori can launch it too. Codex can be launched but has no memory yet.
- **Open any agent anywhere.** orrery agent Atlas starts Atlas's tool in the folder you are in, with its
instructions and memory. The folder's own AGENTS.md or CLAUDE.md still applies as that project's rules.
- **Turn existing chats into an agent.** Pick one or more of your Claude Code or Codex chats from a list and they
become an agent that remembers those conversations. The chats themselves are only read, never changed.
- **Give each agent its instructions.** Who it is and how it works, sent to the model ahead of its memory.
- **Choose how summaries are paid for.** Sign in with your ChatGPT account (the one Codex uses) or OpenRouter, use an
OpenAI, Anthropic or OpenRouter API key, or run a local model server. See Summaries.
- **Let agents read each other.** An agent you allow can look up other agents' memory, read-only.
- **Compact Claude Code sessions for free.** With the optional mod, Claude Code's compaction is answered from the
agent's memory: about two seconds, no additional tokens.
- **Take an agent to another computer.** Keep its memory on your own SSH server or a Cloudflare Worker, encrypted
before it leaves your machine.
- **Back up and restore.** orrery backup snapshots every agent (on Linux, a systemd timer can run it nightly), and
orrery restore puts one back.
- **See what it costs.** Tokens per agent and day, with cache hits and cost.
- **Install once, update in place.** One program, with no Node, npm or Git needed; orrery update and rollback.
Screens
| Agent details | Logins and remotes |
| --- | --- |
| | |
| **Usage** | **Tools** |
| | |
Quick start
You need:
- Linux or macOS, x64 or arm64. On Windows, use WSL. Alpine and other musl Linux is not supported yet.
- At least one coding tool: pi, OMP or Claude Code, installed on its own.
- A way to make summaries: a ChatGPT or OpenRouter account, an API key, or a local model server (see
Summaries).
**1. Install.**
The script checks the download, installs Orrery into ~/.orrery, and asks before connecting it to each coding tool
it finds. It puts the orrery command in ~/.local/bin; add that folder to your PATH if it is not there already.
**2. Start Orrery.**
The first run asks where to keep memory, your first agent's name, its folder and tool, and how to make summaries: a
sign-in or an API key. For a local model server instead, add it to ~/.orrery/config.toml first, as
Summaries shows, and add the agent with **N**.
**3. Open your agent.** On the **Agents** page, select it and press **Enter**. If you started Orrery outside the
agent's folder, it asks whether to open the agent here or there. Its tool starts; quit the tool to come back.
**4. Add more.** Press **N** for a new agent. Start it empty, turn an existing Claude Code or Codex chat into it, or
(once you have a remote) fetch one from another computer.
Getting around the TUI
| Page | Keys |
| --- | --- |
| **1 Agents** | **Enter** open · **i** details · **N** new · **M** summary model · **E** instructions · **C** settings · **s** sort · **/** filter. On an agent's details: **B** browse its memory, **A** archive it |
| **2 Logins** | **A** add or replace a sign-in or key · **T** test · **D** remove · **R** add a remote |