Install. Connect.
Continue.

Qoopia is your own environment for long-term agent memory. Each installation stores its own notes, knowledge, agent spaces and history.

The current signed packages are available for macOS Apple Silicon and Linux x64. Download Qoopia.

Before installing: benefits, requirements and permissions

1. Install your environment

macOS · Apple Silicon

Qoopia requires macOS 15 or later on Apple Silicon. Intel Macs and Windows are not supported.

1. Download the DMG and compare its SHA-256 with the checksum on the release page.
2. Open the DMG, move Qoopia to Applications, then open it.
3. Sign in with Google or your email address. For email, open the confirmation link.

Updating Qoopia on Mac

For an existing Mac installation, quit Qoopia and replace Qoopia.app in Applications once. Keep Application Support and your saved data. This installs the native updater; subsequent releases use Check for Updates in the Qoopia menu. Closing the window keeps Qoopia running in the menu bar.

Linux · x64, glibc 2.34+

Extract the TAR.GZ package. From its extracted directory, run:

./qoopia open

./qoopia open runs while its terminal stays open; your saved memory stays after you close it. To keep Qoopia running without a terminal and start it again after a restart, stop it with Ctrl+C and install it as a user service:

./qoopia service install --commit

On a server without a desktop login, also run loginctl enable-linger $USER so that the service starts after a reboot. Check it with systemctl --user status qoopia; remove it with ./qoopia service uninstall --commit.

Linux needs x64, glibc 2.34 or newer and the ps command (package procps). Run Qoopia as a normal user, not as root.

On a server or over SSH, ./qoopia open keeps running when no browser can be opened and prints an SSH tunnel command for the dashboard. Get a one-time sign-in code with ./qoopia owner-login in a second terminal on that computer.

You do not need to install Bun, Docker or Ollama for these packages. For cloud model features you need internet access and an available supported subscription.

Use an existing server you own

If you already manage a reachable Qoopia server, select that environment:

./qoopia use-server --url https://YOUR-SERVER --commit

Replace the address with your own server. This selects one environment; it does not synchronize two databases. The current environment is shown in the sidebar. A server deployment must provide its own reachable HTTPS endpoint, process supervision and backups.

2. Connect your agents

In your selected Qoopia environment, open Connections. Three independent authorizations have different purposes:

Claude Code / Codex

In Connections, choose your client and Read or Read and add. Apply the prepared setup and complete the client’s OAuth sign-in. Then copy the request from the connection card and send it in that client: its first Qoopia protocol call confirms the connection. No verification code is needed. A local installation can add the settings; for another computer, open the exported .qoopia-connection file with Qoopia there.

For automatic session context, also open Session memory settings in Connections and select Codex or Claude Code. This installs lifecycle hooks. Codex requires a one-time trust review in /hooks. On another computer, import the .qoopia-memory file. It contains a private key: keep it on your own device. An MCP connection alone does not enable session capture.

Claude Desktop · macOS

Choose Claude Desktop in Connections. Apply its local adapter, open the authorization link and approve access to your installation. Restart Claude Desktop and send the request from the connection card in a real conversation: its first Qoopia protocol call confirms the connection. The adapter keeps its credentials outside the Claude configuration.

Claude in a browser

Enable external access in Connections and complete account confirmation. Qoopia prepares an HTTPS address. Add the connection using the official Claude form, approve access and verify it from Claude. Your installation must remain online.

ChatGPT Web / Desktop

ChatGPT Web and Desktop on Mac last passed real-client acceptance on 15 September 2026 with ChatGPT Pro: OAuth, verification, note creation, reading and retries without duplicates. Since then the current consent and automatic connection confirmation have not been re-verified with a real ChatGPT account. Add the HTTPS address prepared in Connections and complete consent. Your account must allow custom MCP connections. Qoopia has no published directory entry. Use a normal ChatGPT conversation and the selected plugin.

Web clients cannot reach localhost. Managed external access makes your running installation reachable; it does not copy its memory into a shared cloud database. Browser MCP access does not automatically capture the full conversation or session events.

Other MCP clients

The owner or steward provides a separate agent identity with suitable permissions. Configure the MCP address and that identity in your runtime. Setup and session capture depend on the client; universal automatic capture is not promised.

Check the whole connection

1. Ask the agent to save a short, non-sensitive test note.
2. Ask it to find that note again.
3. Confirm the expected selected environment and agent identity.

“Saved authorization” means a permission was saved. It does not prove that the remote client has successfully called a memory tool.

3. Understand the boundaries

Your installation stores the memory. Built-in embeddings and keyword search run there. An authorized cloud model can receive permitted context through tool calls; background model features also use the separately authorized runtime. Self-hosting is not a promise that no data leaves your computer.

Each agent has its own identity and permissions. A steward is an agent you authorize to manage the environment. The role does not create or launch a persistent AI process. The same agent may be chosen as the external representative in Bridges.

Sign-in is a separate identity service. Review the current sign-in privacy information. Installer downloads through qoopia.ai/download are counted on our server as they are redirected to GitHub: platform, version and referral type only, with no cookies, stored identifier or IP. Other website analytics (page views, language, screen size and basic performance) is off until you enable it in the footer. Neither includes the contents of your memory or messages. Do Not Track and Global Privacy Control turn both off.

4. Share with Bridges

1. Create a bridge group and generate an invitation. Send it only to the intended participant.
2. The participant requests to join from their own installation. Approve them in Members.
3. Prepare a separate copy in For sending. Publish its title and short description to the group’s catalogue.
4. An admitted participant requests a specific version. Choose Approve sending or Skip. Automatic sending is an explicit option for a specific version and group.
5. The copy arrives in Received. It is not automatically added to ordinary memory, installed as a skill, or forwarded.

Both installations need overlapping uptime for delivery. Received copies cannot be recalled. Pilot limits: 32 member records per group, 100 catalogue records and 1 MiB per item. There is no shared open repository of private notes.

5. What your agents get

• Canons: Short rules for the whole workspace, one agent or one project. Qoopia adds always-on canons at session start and matching ones to each prompt; clients without hooks call canon_match. The steward and the owner write workspace and project canons, an agent can write its own, and the Canon page shows them and lets you retire one.
• Night review: Only the owner appoints the night-review agent, on its agent card or with agent_set_dreamer. It reads the workspace’s conversations for a chosen period with session_review and can propose canons; a proposal becomes a canon only after the owner accepts it in Overview. The review runs on that agent’s own schedule. Other agents see only their own conversations.
• Handoff between Claude Code and Codex: A Claude Code or Codex session with session memory that opens a project receives the latest work another agent of the same owner did there: the final answer, the summary, changed files, tool errors and the last requests, given as history rather than instructions. Shared context must be on. Clients without hooks call work_handoff; work_take marks a topic as taken until the mark expires or is released, and locks nothing.
• Tools: A connected client sees eight core tools: recall, note_get, note_create, agent_inbox, agent_send, qoopia_guide, tool_search and qoopia_execute, plus qoopia_protocol for older connections. tool_search finds the other tools and returns their schemas. qoopia_execute runs a short read-only script in an isolated QuickJS sandbox with the agent’s own permissions, within 10 seconds, 50 tool calls and 20 KB of output; it cannot write and does not use the model.
• Search: recall answers without a model by default. With judge: true, the memory-model subscription can expand the query and judge the candidates within model_budget_ms (1–45 seconds). A server operator can configure an optional, older reranker service; it is off by default, and on an error or timeout the results keep their original order. The Mac and Linux packages need no external search service.

If something is missing

• Download unavailable: Use the official download links on the home page. If a download fails, reload the release page and try again.
• Local address warning: cloud clients need reachable HTTPS, not a localhost URL.
• Wrong environment: check the sidebar host and selected server before saving anything.
• No automatic summary: check the separate model subscription in Memory and its current allowance.
• Old interface: reload after the new-version notice. Save unsent input first.
• Self-check: run qoopia doctor: on Mac /Applications/Qoopia.app/Contents/Resources/bundle/qoopia doctor, on Linux ./qoopia doctor in the package directory. Logs are in ~/Library/Logs/Qoopia on Mac and ~/.local/state/qoopia/logs on Linux.
• Still stuck: report a problem on GitHub. Include the version, platform and doctor output. Never paste tokens, keys or private notes.

Remove Qoopia

If you linked session memory, first run qoopia memory-unlink --runtime claude_code --commit (or --runtime codex). If Qoopia runs as a service, run qoopia service uninstall --commit. Then quit Qoopia: on Mac, choose Quit Qoopia in the menu bar (closing the window keeps it running); on Linux, stop ./qoopia open with Ctrl+C. While Qoopia is running, uninstall stops with “Installation is busy”. Then run qoopia uninstall --commit; on Mac, move Qoopia.app to the Trash afterwards.

Uninstalling keeps your memory: ~/Library/Application Support/Qoopia on Mac, ~/.local/share/qoopia on Linux. Installing again picks it up. Delete that folder only after a backup, and only if you want the memory gone.

Official client references

• Claude: directory and custom connectors
• OpenAI: connect a custom ChatGPT integration