Make project memory part of your workflow.

Install Atlas

You need Node.js 20 or newer, npm, and an MCP client. For remote storage and semantic recall, create a delegate key and account in the Walrus Memory dashboard. The local index uses SQLite; no database server is required.

1. Get the current release

git clone --branch feat/cinematic-landing https://github.com/greyw0rks/atlas.git
cd atlas
cp .env.example .env

2. Configure .env

Edit the file in your Atlas checkout before running the installer. Use the MemWalAccount object ID for MEMWAL_ACCOUNT_ID. The delegate public key will cause authentication errors. Keep the private key in this local, gitignored file.

DATABASE_URL="file:./dev.db"
MEMWAL_PRIVATE_KEY="<your delegate private key>"
MEMWAL_ACCOUNT_ID="0x<your account object id>"
TATUM_API_KEY=""

TATUM_API_KEY is optional and recommended for Sui RPC access. Atlas sends it as x-api-key when configured; keyless availability depends on the gateway.

3. Run the installer

./install.sh

The installer builds and links atlas-mcp, creates the SQLite schema, registers Claude Code and Codex, and adds global session instructions. It backs up Claude settings before editing them, removes hooks that reference HANDOFF.md, and installs the /atlas skill for Claude Code. Restart your client after installation.

git clone https://github.com/greyw0rks/atlas.git
cd atlas && git checkout feat/cinematic-landing
cp .env.example .env   # Fill in your MemWal credentials before continuing
npm install && npm install --prefix mcp-server
npx prisma generate && npx prisma db push
npm run build --prefix mcp-server && npm link --prefix mcp-server

Connect Atlas to Codex

Complete installation first. If you ran ./install.sh, Codex registration and global instructions are already added. Confirm the server with codex mcp list, then restart Codex. For a manual install or an existing Codex setup, follow these steps.

1. Register the MCP server

From the Atlas repository root, run the commands below. They save an absolute server path in ~/.codex/config.toml so Atlas also works when Codex opens another project.

codex mcp add atlas -- node "$PWD/mcp-server/dist/mcp-server/index.js"
codex mcp list

[mcp_servers.atlas]
command = "atlas-mcp"

2. Add instructions for each session

Append this block to ~/.codex/AGENTS.md for all projects, or to AGENTS.md in a single repository. Keep your existing instructions; if an Atlas block is already there, update that block.

<!-- atlas:begin -->
## Atlas memory

Use the Atlas MCP tools for this repository:
- On session start, call atlas_start_session with repoPath = cwd,
  repoName = the directory name, and agentId = "codex".
- Read the returned context, previous session, open tasks, and decisions.
- Save durable facts with atlas_save_memory; use TODO or BUG for tasks
  and ARCHITECTURE for project structure.
- Record choices with atlas_record_decision, including the rationale.
- Before stopping, call atlas_end_session with a brief summary.
- If Atlas tools are unavailable, carry on normally.
<!-- atlas:end -->

3. Restart Codex and verify

Start a new Codex session in the project you want Atlas to remember. Ask it to run the prompt below. A successful tool call returns a session ID and repository ID. A new repository may have no previous session yet.

Start an Atlas session for this repository with agentId "codex".
Summarize the previous session, open tasks, and key decisions.

Connect Claude Code

The automated installer registers Atlas in ~/.claude/settings.json, adds global instructions in ~/.claude/CLAUDE.md, and installs the /atlas skill. Restart Claude Code and run /atlas.

For manual setup, merge the atlas entry below into your existing mcpServers configuration. The atlas-mcp command must be on PATH. Ask Claude Code to start and end Atlas sessions, or add those instructions to CLAUDE.md with agentId set to "claude-code".

{
  "mcpServers": {
    "atlas": {
      "command": "atlas-mcp"
    }
  }
}

Your first session

Atlas records what your agent sends to its tools. Session instructions help the agent use them consistently; Atlas does not automatically capture every conversation.

1. Start: ask the agent to start a session for your repository and review its previous context. For a new project, ask it to scan the repository.
2. Save: ask it to record useful facts, bugs, tasks, and decisions as you work. A successful remote write returns a blobId and storedOnWalrus: true.
3. Recall: ask it to search Atlas for a topic, such as previous authentication decisions.
4. Finish: ask it to create a handoff and end the session with a summary. The next session can retrieve that work.

Save an ARCHITECTURE memory describing how the API shares data with the dashboard.
Record the decision we just made, including its rationale and alternatives.
Search Atlas for previous decisions about authentication.
Create a handoff, then end this Atlas session with a summary.

MCP tool reference

Atlas exposes 15 tools. Your MCP client reads their input schemas; use the sessionId and repoId returned by atlas_start_session for later calls that require them.

atlas_start_session

Start work with repoPath, repoName, and agentId. Returns sessionId, repoId, previous work, open tasks, and decisions.

atlas_get_repository_context

Read a repository's saved context without starting a session.

atlas_save_memory

Save a typed memory with sessionId, repoId, kind, content, an importance score from 1 to 5, and optional tags.

atlas_record_decision

Record a decision's title, rationale, and alternatives for the current session and repository.

atlas_get_open_tasks

List unresolved TODO and BUG memories for a repository.

atlas_get_recent_sessions

Read recent session summaries and memory and decision counts.

atlas_update_context

Update architecture, constraints, techStack, or importantFiles in repository context.

atlas_create_handoff

Generate a handoff describing completed work, failures, next steps, and relevant context.

atlas_search_memory

Recall memory text by meaning through Walrus Memory and attach available local metadata.

atlas_end_session

Finish the session with a summary and optional handoff. Writes portable .atlas/ files in the repository.

atlas_scan_repository

Inspect a repository's stack, README, and important files and update its context.

atlas_extract_git_memories

Extract memories from recent commits and changed files.

atlas_generate_atlas_md

Write ATLAS.md with the project's context, constraints, tasks, and decisions.

atlas_reconstruct_timeline

Read a chronological timeline of the repository's memories and decisions.

atlas_verify_onchain

Look up Sui object IDs and transaction digests through Tatum and return verification details.

Memory kinds: ARCHITECTURE, DECISION, BUG, TODO, WARNING, IMPORTANT_FILE, DEPENDENCY, SECURITY, CONTEXT. Use an importance score from 1 to 5 and optional tags to organize memories.

Storage and recall

Walrus Memory stores uploaded memory text and provides semantic recall. Its relayer handles embeddings, encryption, and Walrus storage on Sui Mainnet. SQLite holds your local session history, context, memory copies, tasks, and verification metadata.

• A record with blobId: null or storedOnWalrus: false has no confirmed remote copy. It remains in your local index.
• Semantic search requires Walrus Memory; there is no local semantic search fallback.
• Back up your SQLite file. Full reconstruction of local metadata from Walrus is not implemented.
• Machines using the same Memory account can recall uploaded text. Local histories and metadata do not automatically sync.
• Recall namespaces use repository names. Give unrelated projects distinct names.

Tatum checks Sui object IDs and transaction digests referenced in memories. Those checks describe the referenced chain data at the time of lookup; they do not validate every claim in a memory.

Run the local dashboard

From your configured Atlas checkout, start the web app:

npm run dev

Open localhost:3000/workspace to browse your repositories, sessions, tasks, decisions, and memories. The dashboard shares the MCP server's local SQLite index. The hosted Atlas website serves documentation; the memory dashboard and its API run on your machine.

Troubleshooting

Codex cannot find Atlas

Run codex mcp list. If atlas is missing, register it from the Atlas checkout using the CLI command above and restart Codex. If the server file is missing, run npm run build --prefix mcp-server from that checkout before registering it.

atlas-mcp: command not found

Restart your terminal after npm link --prefix mcp-server, or use the Codex CLI command with the absolute Node entry point shown above. That method does not require the global atlas-mcp link.

Memory writes fail or return no blob ID

Check your Atlas checkout's .env and network connection. MEMWAL_ACCOUNT_ID must be the account object ID, not the delegate public key. Verify the delegate key belongs to that account and restart your client after changing credentials. A local save alone does not confirm storage on Walrus.

Tatum reports an authentication error

Add a valid TATUM_API_KEY to .env and restart your client. Verification errors are returned per reference.

Update an existing installation

git pull
npm install
npm install --prefix mcp-server
npm run build --prefix mcp-server

Restart Codex or Claude Code after rebuilding. Keep the checkout at the registered path, or register it again if you move it.