Eunomia

curl -fsSL https://www.buildpaperless.com.au/eunomia/install.sh | bash

Shared memory for the AI apps you already use.

Tell one AI app something once, and every app you connect can remember it. Eunomia keeps your people, projects, decisions and documents in one place that you own, and lets ChatGPT, Claude Code, Codex and other AI apps look things up there. You don't need to know what MCP is to set it up.

Connect your AI app · Memory spaces · Get started · How it works · Documentation

See it in action

Watch the launch film (with sound) in 1080p (27 MB) or 720p (4 MB): your agents forget, Eunomia remembers, and every agent recalls what the team decided.

What's new in 2.0.8: a calmer, clearer app

Release 2.0.8 brings the Eunomia Bauhaus app design: one obvious next step on every screen, written for people who are not technical.

• Home asks one question first: "Which AI app do you use?" Pick ChatGPT, Claude Code, Codex or Other apps (nothing is chosen for you) and you see only that app's steps. Browser setup and terminal setup are kept separate.
• Plain names everywhere. The sidebar reads Home, Chat, People & topics, Memory spaces, Documents, Connected sources, Help and Settings, with AI instructions and Code map under Advanced.
• Honest status. "Connected" only appears after Eunomia itself has seen your app sign in. Every status is written in words, not just a coloured dot, and anything you can't undo asks first, naming exactly what will change.
• Works for everyone. Keyboard and screen-reader friendly, large touch targets, readable contrast, a menu drawer on small screens, and less motion when your device asks for it.

The design system (colours, type, layout and component rules) is documented in DESIGN.md.

Connect your AI app in four steps

1. Choose your AI app. Open Eunomia; Home shows ChatGPT, Claude Code, Codex and Other apps.
2. Follow its steps. ChatGPT is set up in your browser (it needs Eunomia on a public https:// address). Claude Code and Codex are set up with one command you copy into your computer's command window; the guide tells you how to open it on Mac, Windows or Linux.
3. Sign in and approve. Your app opens Eunomia's sign-in page. Use your Eunomia email and password, read what the app is asking to do, and choose Allow.
4. Try it. Start a new conversation and ask "Use Eunomia to look for memories about me." Press Check connection in Eunomia to confirm. Finding no memories on a new account is normal: the connection works, there is simply nothing saved yet.

Stuck? Connection help (linked from every guide) covers the usual problems: not sure which app, ChatGPT has no custom-connection option, "command not found", no sign-in page, or no memories found.

Prefer to do it from a terminal? The installer connects the AI apps it finds on your computer, and ./scripts/connect-agents.sh does it again later. Exact commands and config for each app are in AI agents & MCP.

Memory spaces

A memory space keeps one part of your life or work together: your own notes, a client, a project, a team. Everything your AI apps remember goes into a space, and only the people in that space can read it.

• Your personal space is created with your account and is private to you.
• Shared spaces are for projects and teams. Invite people by email; they get access only after they accept. Every space always keeps at least one owner.
• Copy or combine. Copy space makes a new space with the same memories. Combine two spaces makes a new space with both, and leaves the two originals unchanged.
• Share with another Eunomia on your network. An owner can make a one-time share code; someone running their own Eunomia joins with it and gets a full copy of that space that stays in step with yours (changes are exchanged every half minute over an encrypted, authenticated link). Only the owner's Eunomia needs to be reachable.

In the API and agent tools a memory space is called a vault; the technical details are below.

Connected sources

Bring in what you already have. Choose a source, check that the connection works, then import: Eunomia shows where items will go before it starts, honest progress while it runs, and how many items arrived when it is done. Sign-in problems and import problems are reported separately, each with a way to retry.

Built-in sources include GitHub, Slack, Notion, Linear, Gmail, Google Calendar, Discord, Todoist, Stripe, Up Bank, Spotify, Ed Discussion and PocketAI. You can also upload documents (text, Markdown, JSON, CSV and text PDFs); their passages are found by the same search your AI apps use. See Connectors for the full table.

Why Eunomia?

An agent's conversation ends; the things it learned should stay useful. Eunomia is a self-hosted memory service built around vaults (memory spaces in the app): separate spaces for the knowledge your agents read and update over MCP or REST. Each vault holds its own entities (people & topics), memories and relationships, with access controlled by membership.

• Choose the memory scope. Use a personal vault or a named project/team vault; share access through invitations.
• Remember across sessions. Save facts and experiences about people, organisations, locations and code.
• Find context in several ways. Recall combines semantic search, keywords, memory text, graph links and explicit date ranges.
• Bring in your apps. Sync records from the built-in sources, then search them alongside remembered facts.
• Run it for a team. Each org gets its own database, and tokens can be scoped, limited to one vault and set to expire.
• See what's stored. Explore people & topics and code maps, inspect memories, or compare vaults in a 3D vector cloud.

Vaults (memory spaces) in detail

A vault is the unit of organisation and sharing in Eunomia. Keep a client's facts, a project's decisions or a team's working knowledge in its own vault. The same person or repository can appear in several vaults, with different memories and relationships in each.

flowchart TD
    A[Your agents: Claude Code, Codex, Hermes and more] --> B[Authenticated tools and active vault membership]
    B --> P[Personal vault]
    B --> J[Project vault: Acme]
    B --> T[Shared team vault]
    P --> PM[Your entities, facts and relationships]
    J --> JM[Project entities, facts and relationships]
    T --> TM[Team entities, facts and relationships]
    C[Invited collaborators] --> B

Vault operation	What it gives you
Create	A named space for a project, client, team or service; your personal vault is created with your account
Share	Invite collaborators with owner/member roles; access begins when an invitation is accepted
Invitations	See the invitations addressed to you and accept or decline them, from the app or as an agent
Roles and ownership	Promote or demote members, or hand a vault to another member; a vault always keeps at least one owner
Scope	Pass a vault name or ID as vault_id to target its memory; membership is checked on every read and write
Clone	Copy a vault's entities, memories and relationships into a new vault you own
Merge	Combine two vaults into a new one, folding matching entities and deduplicating facts and relations; both originals stay intact

Writes go to your personal vault by default. Name a vault to write into its project or team context. Without vault_id, recall, reflect and entities_search search your personal vault plus the project/team vaults you belong to. Recall hits identify their vault; an explicit vault narrows the search. Another user's shared personal vault is searched only when named.

Sharing a vault shares its memory graph. Raw synced connector records remain owned by the user who connected the source. Removing a member or leaving a vault takes effect on the next call. A token limited to one vault uses that vault as its default and cannot reach any other.

Vaults live inside an org. A self-hosted install is one org by default, so everyone who signs up can be invited to its vaults; each org's data sits in its own database.

Vault management works from the app and from your agents' tools alike. Open vault and entity views refresh periodically, so an agent's changes show up without a reload.

Explore vault concepts and the source-linked vault architecture.

Get started

Use Linux or macOS, or WSL on Windows. The installer checks for git, Docker with Compose, and other prerequisites, and offers to install missing tools.

It starts the database, backend and web app, sets up updates and nightly backups, creates your account, and connects supported agents. Open localhost:3000, sign in, then restart your agent so it loads the MCP server.

Try asking it:

Create a vault called Acme. In Acme, remember that Ada prefers async updates over meetings.

Then, in another session:

In the Acme vault, what do you know about Ada?

No model key is required for agent-written memory or text/graph recall. Your connected agent uses its own model. To enable semantic search, automatic entity extraction, observation synthesis and in-app chat, configure an OpenAI-compatible endpoint in Settings. Auth-free self-hosted endpoints can work without a key; embeddings must return 1,536-dimensional vectors.

See Quickstart for the first run and Installation for manual setup and installer options.

To give a repo's agents one shared vault and skills, run npm create eunomia in it. See Projects.

Upgrading from 1.x

2.0 moves to SurrealDB 3.3 and gives each org its own database. Any 1.x install can update straight to 2.0 with Update now in Settings (instance admins only). Taking the 1.4.2 bridge release first is recommended, not required: its updater also puts the old release back if the move fails.

During the update Eunomia takes an encrypted pre-v3 backup, copies your data to a new SurrealDB 3 volume, checks every table's row count, and rolls back to the old volume if anything doesn't match. On its first boot, 2.0 then moves the single database into one org, verified the same way; the old database is kept until you remove it. The app is offline while this runs; plan for about four times your current data volume in free disk.

Keep ENCRYPTION_KEY: it now also protects each org's database password. If a move fails, the reason is in docker compose logs surreal-upgrade; fix it and run docker compose up -d from the install folder to try again. See Upgrading to SurrealDB 3 and Org databases and the one-time move.

How it works

Explore the interactive architecture (download and open locally) · Read the underlying workings

1. Choose a vault. Agents write into your personal vault or a named project/team vault, with membership checked before access.
2. Collect. Sync jobs, queued on each source's schedule or by Sync now, and supported webhooks map app data into a common record format.
3. Store and enrich. Records and links are upserted into the org's database. When a model is configured, records are embedded, and background jobs extract entities and facts and consolidate observations.
4. Recall. Five retrieval paths produce candidates. Reciprocal Rank Fusion combines their ranks; recency and agreement between paths adjust the results.
5. Use. Agents, REST clients and in-app chat call one shared tool registry to recall, reflect, write memories and manage graphs and vaults.

Records and memories are distinct: synced records belong to a user; memories belong to a vault. Sharing a vault shares its memories, without sharing a member's raw connector data. The code graph is populated by agent calls to code_entity_upsert and code_relate.

Each org's data lives in its own SurrealDB database, reached through that org's own database user, so a query for one org cannot read another's. Accounts, tokens, the audit trail and the job queue live in a separate control database. Background work runs as leased jobs with retries, so a job from a crashed worker is picked up again.

Connect your agents and apps

The installer supports Claude Code, Codex, Hermes, Gemini CLI, Cursor, Windsurf, OpenCode, VS Code and Claude Desktop. To connect more agents later:

./scripts/connect-agents.sh

The MCP endpoint is <your Eunomia URL>/mcp. Agents authenticate with a personal access token, which can be scoped, limited to one vault and set to expire, or sign in through MCP OAuth 2.1. REST clients use the same token with POST /api/tools/:name. Browser sessions use signed cookies. Mutating tool calls are audit-logged. See AI agents & MCP for configuration and the complete tool list.

Source	Data you can bring in
Up Bank, Stripe	Banking and payment records
HeyPocket	Meeting recordings and transcripts
GitHub, Linear, Notion, Todoist	Issues, pull requests, documents and tasks
Slack, Discord, Gmail, Google Calendar	Messages, mail and calendar events
Ed Discussion	Course discussion threads, with answers and comments
Spotify	Listening history

Set credentials and source options on the Connected sources page (/connectors). Connector secrets are encrypted at rest with AES-256-GCM. Up Bank supports signed webhooks; other sources use their sync adapters. A synthetic demo source is available for on-demand test data. See Connectors for setup details.

Develop locally

You need Rust, Bun and Docker. From the repository root, create .env if it doesn't already exist:

cp .env.example .env
openssl rand -base64 32

Put the generated value in ENCRYPTION_KEY. Set a stable JWT_SECRET too if you want browser sessions to survive backend restarts. Then run:

./run.sh

This starts SurrealDB 3.3.5 in Docker, the Rust backend on :8001, and Next.js on :3000. The frontend proxies /api/* and /mcp to the backend. A dev volume last used with SurrealDB 2.x must be removed or upgraded first. The Compose stack uses prebuilt images; see Installation for that path.

Run checks from the repository root:

(cd backend && cargo test --release)
bash scripts/tests/connect-agents.test.sh
bash scripts/tests/auto-update.test.sh
bash scripts/tests/https.test.sh
(cd frontend && bun run lint && bun run build && bunx tsc --noEmit)

With the stack running and system Chrome installed:

(cd frontend && E2E_BASE_URL=http://localhost:3000 bun run test)

CI runs clippy and the backend tests (also under the hardened SurrealDB settings, plus the org isolation proof), every script test, the frontend checks, Playwright against the Compose stack built from the repository with SurrealDB 3.3.5, the 2.x to 3.3 upgrade, and restore drills. The recall evaluation measures Recall@5 and MRR on a fixed corpus, and checks for cross-vault and cross-user leaks. See Testing for every layer.

Errors carry a stable code and a trace id (RFC 9457 problem+json); logs are JSON, and OpenTelemetry export is optional. eunomia-backend replay <trace_id> re-runs a recorded failure. See Errors, Debugging and Observability.

Deploy and back up

Use Deployment for HTTPS, production secrets and updates. The backup service takes an encrypted export of every database (control and each org) nightly into the eunomia-backups volume. Set BACKUP_ENCRYPTION_KEY in .env and keep a copy off the machine. With the stack running:

backend/scripts/backup.sh               # back up now
backend/scripts/backup.sh list          # list backups
backend/scripts/restore.sh <file> --wipe

Without --wipe, restore replays the dump over existing data. scripts/restore-drill.sh proves a backup restores, using a throwaway database. See Backups. docker compose down -v deletes the data volumes.

Documentation

Guide	What it covers
Quickstart	Install, sign in and remember your first fact
Installation	Installer flags, manual setup and supported platforms
AI agents & MCP	Agent configuration, tokens, OAuth and every tool
Projects	npm create eunomia: one vault and shared skills per repo
Concepts	Vaults, facts, observations, graphs and the vector cloud
Underlying workings	Source-linked architecture, tenancy, jobs, ingestion, retrieval and access checks
Connectors	Source credentials and sync setup
Deployment	HTTPS, secrets, updates, org databases and backups
Upgrading to SurrealDB 3	The 1.x to 2.0 database upgrade, rollback and recovery

The core user guides are also available on the app's Help page and through the docs MCP tool. Developer references are listed in the docs index.

Support

Questions, bugs or commercial licensing: [email protected]. Bugs and feature requests can also go in GitHub issues.

License

Free for personal and noncommercial use under the PolyForm Noncommercial License 1.0.0. Commercial use needs a paid license: email [email protected].

© Midhun Kumar