Set up Auric
Auric gives your project persistent context that your AI coding tools and agents can reconnect to across sessions.
After setup, compatible AI coding tools such as Claude Code and Cursor connect to the same Auric project context on your machine.
About 10 minutesKeep your invite email openNo account needed
What you’ll be able to do
- Continue a project in a new session without re-explaining it
- Use the same project context from Claude Code, Cursor or another MCP tool
- Hand work from one agent to the next
- Save and read back the goal, decisions, open items and next step
Already ran the four commands from your email? Skip to step 5: connect your tool.
Step 1: Check requirements
- Node.js 18 or newer — it includes npm
- An AI coding tool that supports MCP: Claude Code, Cursor or similar
Open a terminal (PowerShell on Windows) and run:
node --version
npm --versionYou should seeTwo version numbers, the first starting with v18 or higher.
Missing, or older than 18? Install the LTS version from nodejs.org, then open a new terminal.
Step 2: Install Auric
Paste the first command from your invite email. It looks like this, with your personal download link:
npm install -g "https://www.auric.cx/api/download/…"What this doesDownloads your personal copy of Auric and installs the auric command.
You should seenpm finishes without errors. To check, run auric version — it prints auric 1.3.0.
The link is personal to you — please don’t share it. If the install fails, see troubleshooting.
Step 3: Add your license
Paste the second command from your email:
auric license <your license key>What this doesChecks your personal beta license and saves it on this computer. Nothing is saved if the key doesn’t check out.
You should seeA line starting auric: license for, with the date it’s valid until.
Step 4: Initialize Auric
auric initWhat this doesPrepares Auric’s local storage on your machine, in ~/.auric. Run it from any folder; no Git repository is required, and running it again is safe.
You should seeA line starting auric: initialized.
Step 5: Connect your AI coding tool
Auric connects to your AI coding tool through MCP (Model Context Protocol) — the standard way these tools add capabilities. You only set this up once per tool.
Using more than one tool? Connect each one. They all use the same Auric storage on this machine — that’s how Claude Code and Cursor see the same project context.
Jump to: Claude Code · Cursor · another MCP tool
Claude CodeOne command
In your terminal (macOS or Linux), run:
Terminalclaude mcp add --env DATABASE_URL="file:$HOME/.auric/auric.db" \ --scope user auric -- auric serveWhat this doesAdds Auric to Claude Code for all your projects, with the same settings
auric configprints.If
auric configshows a different DATABASE_URL, use that value instead. On Windows, use the project file below.Check the connection:
Terminalclaude mcp listYou should seeauric: auric serve - ✔ ConnectedStart Claude Code in your project folder (restart it if it’s already open). Type
/mcp— Auric is listed as connected.
Prefer a per-project file, or on Windows?
- 1. Run auric config
- 2. Copy the output
- 3. Paste into .mcp.json
- 4. Restart
- 5. Approve
Run
auric configand copy the JSON it prints — from the first{to the last}, without the hint lines after it.In your project’s root folder, create or open
.mcp.jsonand paste it. If the file already has anmcpServersobject, add just theauricentry inside it, separated by a comma.Restart Claude Code in that folder and approve Auric when asked.
/mcpshows it as connected.
The path in this file is specific to your machine, so keep the change out of your Git commits. Claude Code MCP docs.
CursorPaste once
- 1. Run auric config
- 2. Copy the output
- 3. Paste into ~/.cursor/mcp.json
- 4. Restart Cursor
- 5. Check it's on
Run:
Terminalauric configIt prints this — your path will differ{ "mcpServers": { "auric": { "command": "auric", "args": [ "serve" ], "env": { "DATABASE_URL": "file:/Users/you/.auric/auric.db" } } } }Copy everything from the first
{to the last}. The lines after it are hints — leave them out.Open
~/.cursor/mcp.jsonin your home folder (Windows:%USERPROFILE%\.cursor\mcp.json). Create the file and the.cursorfolder if they don’t exist.- New or empty file: paste the whole block.
- Already has servers: paste only the
"auric": { … }entry inside the existingmcpServers, with a comma between entries.
Save. This makes Auric available in all your Cursor projects.
Restart Cursor.
Open Customize → MCPs in Cursor’s sidebar. Auric is listed and switched on, and its tools appear in the tools list at the top of the chat panel. Cursor asks you to approve Auric’s tools the first time an agent uses them.
Auric shows an error instead? If you installed Node.js with a version manager such as nvm, Cursor may not see it — here’s the fix.
Another MCP tool
Add a local (stdio) MCP server that runs the command auric with the argument serve, and set the environment variable DATABASE_URL to the value auric config prints. Most tools accept that mcpServers block as-is.
Use the same DATABASE_URL in every tool, so they all share one Auric project context. Not sure where your tool keeps its MCP settings? Reply to your invite email.
Step 6: Verify
Two checks — one for Auric, one for your AI coding tool.
Auric
auric doctorauric doctor (v1.3.0, file:…/.auric/auric.db):
PASS database reachable
PASS WAL journal mode (persisted)
PASS migrations up to date
PASS beta license (serve)All PASS?Auric is ready. A FAIL line names the command that fixes it — or see troubleshooting.
Your AI coding tool
Auric shows as connected: type /mcp in Claude Code, or open Customize → MCPs in Cursor. auric doctor can’t see your tool, so check both.
When both checks pass
Auric is connected.
Your AI coding tool can now save and read Auric’s persistent project context. Setup proved Auric is installed — the next two minutes prove it’s useful.
Try it nowStep 7: Try Auric
Open a project in your AI coding tool — something you’re working on, or any folder. Two prompts, about two minutes.
First: save where the project stands
Use Auric to save where this project stands. Use this folder's name as the Auric project ID. Save the current goal, the important decisions so far and why they were made, anything still unresolved, and the next step. Work out what you can from the project files and ask me about anything you can't. Then tell me the project ID you used.
What happensYour agent reads the project, then saves the goal, the decisions and why, open items and the next step to Auric. Expect a few approval prompts, one per Auric tool it uses — approve them (your tool may offer to remember the choice). It finishes by telling you the project ID — the folder’s name.
Then: start fresh and catch up
Start a new session — type /clear in Claude Code, or open a new chat in Cursor — and paste:
Use Auric to catch me up on this project. The Auric project ID is this folder's name. Tell me the goal, the key decisions, what's still open, and the next step.
You should seeThe goal, decisions, open items and next step you just saved — in a session that never saw that conversation.
That’s Auric: when a session ends, the project’s context doesn’t.
Try a handoff (optional)
Across tools. If you connected two tools, open the same folder in the other one — Cursor if you started in Claude Code, or the other way round — and paste the catch-up prompt. It reads what the first tool saved. No chat is copied; both read the same Auric project context.
Between agents. When an agent finishes a piece of work, ask it to:
Before you stop, use Auric to record what you did, what you decided and why, anything still unresolved, and the next step. The Auric project ID is this folder's name.
Then give the next agent — a new session, a subagent, or another tool:
Use Auric to catch up on this project (the Auric project ID is this folder's name), then continue from the recorded next step. When you're done, use Auric to record what you did, anything you resolved, and the new next step.
You should seeThe next agent starts from the recorded next step instead of asking you what’s going on, and records its own progress for whoever comes after it.
Make it a habit (optional)
Your agent uses Auric when asked. To have it catch up at the start of each session and save as it works, add this to CLAUDE.md (Claude Code) or AGENTS.md (Cursor) in your project’s root folder:
## Auric
This project uses Auric for persistent project context. Use this folder's name as the Auric project ID.
- At the start of each session, use Auric to catch up on the project before starting work.
- When you finish a piece of work or make a decision, save it to Auric: what changed, decisions and why, anything unresolved, and the next step.ThenYou no longer have to start prompts with “Use Auric” — your agent checks it on its own instructions.
Good to know
What this beta doesn’t do, so nothing surprises you:
- It doesn't capture anything on its own. Your agent saves to Auric when you, or your project instructions, ask it to.
- It doesn't copy chats between tools. Tools share the saved project context, not conversations.
- It doesn't assign work or coordinate agents running at the same time. Agents hand over in turn, and the latest update is what the next one sees.
- It stays on one machine. Sharing with teammates or across computers isn't part of the beta.
Troubleshooting
Find the step that went wrong. Each answer starts with what you can fix yourself.
Installing
npm: command not found (or node: command not found)
node --version.node --version shows a version below 18
EACCES or “permission denied” during npm install -g
sudo. On macOS or Linux, follow npm’s guide (installing Node with a version manager fixes it). On Windows, use a Node.js install your user account can write to. Then run the install command again.The install fails with 403
The install fails with 503, a timeout or a network error
The install fails with 429 (too many attempts)
auric: command not found after installing
auric version. If it’s still missing, your terminal can’t see npm’s global commands: npm prefix -g shows where they went, and that folder’s bin needs to be on your PATH. Still stuck? Reply to your Auric invite email. Include your OS and the install output.License
auric license says the key is invalid
auric license <your license key> again. Nothing is saved until a key checks out, so retrying is safe. Still stuck? Reply to your Auric invite email.The license has expired
auric license and the new key, then restart your AI coding tool.The license has been revoked
Initializing
auric init fails
auric init once more — it’s safe to repeat. If it fails again, reply with the error. Don’t delete Auric’s storage to fix it: that’s your saved project context.auric doctor says to run auric init
auric init, then auric doctor, then restart your AI coding tool.Auric shows as failed after an update
auric init, then restart your AI coding tool. Your saved project context is kept.Connecting
claude: command not found
claude mcp list shows auric as ✘ Failed to connect
- Run
auric doctorand fix any FAIL line — each one names the command to run. - Run
auric config. If its DATABASE_URL differs from the one in the command you ran, remove Auric withclaude mcp remove auric -s userand add it again using that value. - Still failing? See “My AI coding tool can’t find auric”.
Cursor doesn’t list Auric
- Check the file is
~/.cursor/mcp.jsonin your home folder (Windows:%USERPROFILE%\.cursor\mcp.json). - Check it’s valid JSON: one
mcpServersobject, theauricentry inside it, commas between entries, and none of the hint linesauric configprints after the closing brace. - Restart Cursor, then open Customize → MCPs and make sure Auric is switched on.
My AI coding tool can’t find auric (spawn auric ENOENT)
Apps opened from the Dock or Start menu don’t always see the same PATH as your terminal — common when Node.js comes from a version manager such as nvm. Give the tool full paths instead. In a terminal, run which node (Windows: where node) and npm root -g, then change the Auric entry to use them:
"auric": {
"command": "<output of which node>",
"args": ["<output of npm root -g>/auric-continuity/bin/auric.mjs", "serve"],
"env": { "DATABASE_URL": "<the value auric config printed>" }
}In Claude Code, the same fix is claude mcp remove auric -s user, then the add command with "<node path>" "<script path>" serve after the --.
Save, restart the tool and check again. Still stuck? Reply to your Auric invite email.
First use
Auric comes back empty, or says there’s nothing saved
auric projects to list the saved IDs, then tell your agent which one to use: “The Auric project ID is demo-shop.”My agent doesn’t use Auric
Need help?
If anything doesn't work, reply to your Auric invite email.
Include your operating system, the output of node --version, your AI coding tool, the step that failed, and the exact error. Remove your license key and download link first.
Want the deeper model? Read how Auric works.