Atlas prevents AI coding agents from silently reversing your project's engineering decisions across sessions.
Atlas is a project memory tool for Codex. It saves important engineering decisions, keeps the reasons attached to them, and brings the relevant ones back when a new task starts. If a request goes against an earlier choice, Atlas warns before work begins.
I built it for OpenAI Build Week in the Developer Tools track. It is not a generic chat-memory system or a background transcript recorder. The point is narrower: help Codex remember the engineering intent of a project without replaying whole conversations.
AI coding agents can start a fresh task without the reasoning behind a project's earlier choices. That makes it easy to repeat debates or accidentally reverse architecture.
Atlas makes the durable context available again:
- A Codex task records a material decision, its rationale, affected files, and optional UI/design context.
- A later task retrieves only the relevant decisions and running project summary.
- If the new request conflicts with prior engineering intent, Atlas returns the original decision and reason before implementation starts.
- The dashboard provides a searchable, project-scoped audit trail of decisions and conflict overrides.
The result: fresh Codex tasks can stay aligned with the project instead of starting from zero.
For a concise recording flow, see the Build Week demo script. For product internals, storage behavior, retrieval flow, and self-testing, see the Atlas product explainer.
Codex is strongest when it has the right context. The hard part is that engineering context changes shape over time:
- one task decides to use PostgreSQL;
- another task starts fresh and no longer sees that decision;
- a later prompt asks for MongoDB or a conflicting pattern;
- the agent can confidently implement the wrong thing because the prior decision is missing.
Atlas solves this by storing decisions as structured project memory. A new Codex task can ask Atlas for relevant context before work begins, search memory during work, and log important decisions after work. If the new prompt conflicts with prior memory, Atlas returns the original decision and reason before the mistake becomes code.
- MCP server for Codex with
get_context,log_decision,search,edit_memory,remove_memory, andoverride_conflict. - Project-scoped memory backed by SQLite, local Docker PostgreSQL, or an existing PostgreSQL database.
- PostgreSQL + pgvector support for realistic shared/team retrieval.
- Offline deterministic mode when no OpenAI API key is configured.
- Optional OpenAI API mode for richer extraction, embeddings, summaries, curation, and conflict checks.
- Fresh-session mode that injects no prior memory but still permits new decisions to be logged.
- Structured UI/design context capture and direct injection for UI-related tasks.
- One-page dashboard for decisions, conflicts, design context, storage state, and estimated context avoided.
- Doctor command for setup/debug checks before changing storage.
- Attach command for using one Atlas install across many Codex projects.
- Optional dashboard/API PIN for local-network-ready deployments.
Codex task
|
| MCP tools
v
Atlas MCP server
|
| starts local API on demand
v
FastAPI service
|
+-- SQLite for simplest local demo
+-- PostgreSQL + pgvector for shared or production-like memory
Codex starts the Atlas MCP server using the command in a Codex config file. Codex Desktop reads the server list from the user-global file at ~/.codex/config.toml, so atlas attach always writes the Atlas server there first. It also writes a small project-local .codex/config.toml (used by the Codex command-line tool and to record the project name). The MCP server starts the local FastAPI service only when a tool call needs it. The database stores projects, sessions, decisions, embeddings, structured design context, and conflict events.
Atlas is intentionally not a background transcript recorder. It stores only material engineering decisions that pass extraction and validation.
Download AtlasSetup.exe from the project's GitHub Release, run it, select Add Atlas to my user PATH, and select Run Atlas setup now on the final installer page.
When setup opens, choose SQLite. Then create or open a small project folder and attach it:
mkdir C:\AtlasJudgeDemo
cd C:\AtlasJudgeDemo
atlas attach . --project-name atlas-judge-demoOpen a fresh Codex task in C:\AtlasJudgeDemo, run /mcp to confirm atlas is enabled, then ask Codex to use Atlas before changing architecture. The first Atlas tool call starts the local API. Open http://127.0.0.1:8000/dashboard/ to view saved memory.
This is the self-contained Windows path for judges who choose to run from source. It needs no Docker, cloud database, Node frontend, or OpenAI API key.
-
Clone the repository and open PowerShell in its root folder.
-
Create the Python environment and run setup:
py -3.11 -m venv .venv .\.venv\Scripts\python.exe backend\scripts\setup.py
-
Choose SQLite when asked. Setup installs dependencies and writes the install-level
.envand registers the Atlas MCP server in your Codex config (the global file for Codex Desktop, plus a project-local file). -
Check the installation:
.\.venv\Scripts\python.exe backend\scripts\doctor.py .\.venv\Scripts\python.exe -m pytest backend\tests -q
-
Open a fresh Codex task in the repository folder and run
/mcp;atlasshould be enabled. -
Ask Codex to use Atlas before changing architecture. The first Atlas tool call starts the local API automatically.
-
Open
http://127.0.0.1:8000/dashboard/after that first tool call to view the timeline, conflict evidence, design context, and editable saved memory.
To test the full loop, log a Decision: plus Reason:, start a fresh task and retrieve context, request a contradictory change, then open the dashboard. See docs/DEMO_SCRIPT.md for exact demo text.
| Mode | Best for | Strengths | Limits |
|---|---|---|---|
| SQLite | Fastest judge/demo path | No Docker, no network, single local file | Local JSON embedding ranking instead of pgvector indexes |
| Local Docker PostgreSQL | Realistic local development | PostgreSQL, pgvector, migrations, durable Docker volume | Docker Desktop must be installed and running |
| Existing/cloud PostgreSQL | Build Week demo reliability and sharing | Durable outside the laptop, no local Docker dependency, production-like retrieval | Needs database URL and network access |
For a live Build Week demo, cloud PostgreSQL is the strongest story if the database is already stable. SQLite is the safest emergency fallback.
-
Create and activate a virtual environment.
py -m venv .venv -
Run setup.
.venv\Scripts\python.exe backend\scripts\setup.py -
Choose storage:
- Local Docker PostgreSQL managed by Atlas.
- Local Docker PostgreSQL started manually.
- Existing PostgreSQL URL.
- Local SQLite.
-
Setup writes:
.envwith Atlas settings.- your Codex config with the Atlas MCP command and server (written to the global
~/.codex/config.tomlfor Codex Desktop, and a project-local.codex/config.toml). work/.requirements.sha256so repeated setup runs can skip dependency reinstall when requirements have not changed.
-
Open a fresh Codex task from this project folder. If Codex was already open before setup, close that task and start a new one.
When Atlas feels broken, run:
.venv\Scripts\python.exe backend\scripts\doctor.pyThe doctor checks:
- supported Python version;
- active virtual environment;
- dependency imports;
.codex/config.toml;- selected storage settings;
- Docker command and daemon where relevant;
- database connectivity;
- SQLite schema initialization or PostgreSQL Alembic migration revision;
- local API health.
It is normal for the API health check to warn when no Atlas MCP process is currently running. Atlas starts the API on demand.
After setup, daily use is simple:
- Start Docker Desktop only if using Docker PostgreSQL.
- Open Codex in this project folder.
- Open a fresh task.
- Confirm
/mcplistsatlas. - Use Atlas tools as part of the Codex workflow.
The MCP process is owned by the Codex task. The local API may remain alive on the configured port until it is stopped, the task exits cleanly, or the machine shuts down. Use atlas stop when you want to free the port or force a clean API restart. Memory remains in SQLite, the Docker PostgreSQL volume, or the configured cloud database.
After atlas attach, Codex can see the Atlas MCP tools in fresh tasks, but v1 is still an explicit MCP workflow rather than a background watcher. To make tool use consistent, atlas attach also creates or updates the attached project's active Codex instruction file:
- If
AGENTS.override.mdalready exists in the target folder, Atlas updates that file because Codex gives it priority. - Otherwise Atlas creates or updates
AGENTS.md. - Existing user instructions are preserved. Atlas only manages the block between
ATLAS-CODEX-INSTRUCTIONS:STARTandATLAS-CODEX-INSTRUCTIONS:END. - Use
atlas attach --no-agents ...if you only want the MCP config and prefer to manage instructions yourself.
The Atlas block says:
Before making architecture, storage, API, data-model, or UI-pattern changes, call Atlas `get_context` with the user's request.
During work, use Atlas `search` when prior project decisions may matter.
After a material engineering decision is made, call Atlas `log_decision` with the decision, reason, and affected files.
If Atlas reports a conflict and the user chooses to continue, call Atlas `override_conflict` with the reason.
Use Atlas `edit_memory` or `remove_memory` only when the user explicitly asks to correct or delete saved Atlas memory.
Every Atlas tool accepts an optional `project_name`. Before calling any Atlas tool in this project, read `.codex/config.toml` in this project folder, find `ATLAS_PROJECT_NAME` under `[mcp_servers.atlas.env]`, and pass that exact value as `project_name`. This keeps each project's memories separate. If the file or value is missing, omit `project_name` and Atlas will use the current folder name.Start a fresh Codex task after changing these files. Codex reads project instructions when the session starts, so an already-open task may not see the new guidance.
get_context(prompt, fresh_session=false)
Retrieves project-scoped memory for a new task. It returns the running summary, relevant decisions, direct UI/design JSON when appropriate, and any conflict warning. When fresh_session=true, Atlas returns no injected memory but does not disable future decision logging.
log_decision(exchange)
Extracts and stores a material engineering decision, its reason, affected files, embedding, optional structured design context, and the updated running summary. If the exchange contains no real decision, Atlas stores nothing.
search(query, limit=10)
Performs explicit mid-task recall against project-scoped decisions.
remove_memory(...)
Removes one decision, a list of decisions, a UTC date range, or all project memory. Whole-project deletion requires the exact confirmation phrase DELETE ALL PROJECT MEMORY.
edit_memory(decision_id, decision?, reason?, affected_files?)
Edits one known saved memory. Use search(...) first when you need its decision ID. Atlas recomputes the memory embedding and rebuilds that project's running summary after every edit.
override_conflict(conflict_event_id, reason)
Records a deliberate, auditable exception when a developer chooses to continue despite a conflict warning.
Offline deterministic mode works best with explicit decision markers:
Decision: Use PostgreSQL with pgvector for Atlas memory.
Reason: It keeps decisions project-scoped and supports local vector retrieval.
Affected file: backend/app/db.py
For UI work, include structured design context:
Decision: Use compact dashboard tabs for Atlas memory review.
Reason: Judges need to scan decisions, conflicts, design evidence, and system state quickly.
Design context: {"colors":{"accent":"#38d9a9"},"spacing":{"card":12},"components":["tabs","timeline","conflict panel"]}
Affected file: dashboard/app.js
With ATLAS_OPENAI_API_KEY, Atlas can extract decisions from more natural exchanges and use semantic embeddings/model-assisted curation.
After Atlas starts the local API, open:
http://127.0.0.1:8000/dashboard/
The dashboard shows:
- project selection;
- newest-first decision timeline;
- an edit-and-save form for each decision (including reason and affected files);
- conflict events and override reasons;
- stored design-context records;
- active storage and intelligence mode;
- estimated context avoided.
The context numbers are estimates, not billing claims. Atlas estimates how much context payload was avoided compared with carrying a larger long-session history forward. It does not claim to measure provider cache hits, invisible reasoning tokens, or final invoice savings.
Every decision, context lookup, search, design-context lookup, deletion, and conflict event is filtered by project_id.
The default project is created from the configured project name. If multiple workspaces share one database, set a unique ATLAS_PROJECT_NAME in each .env before the first Atlas call. Passing a specific project_id is an advanced/manual action.
Global memory and linked-project memory are intentionally deferred to v2.
Teams can share one project's Atlas memory today by using the same cloud PostgreSQL database URL and the same --project-name on every member's machine. Each teammate installs Atlas locally, chooses Existing PostgreSQL URL during atlas setup, then runs:
cd C:\path\to\the\team-project
atlas attach . --project-name bizlive-dashboardDo not copy another teammate's Codex config (the global ~/.codex/config.toml or the project's .codex/config.toml); it contains an absolute path to that person's Atlas installation. atlas attach generates the correct config for each person. The shared project name resolves to the same project ID in the common database. Atlas v1 assumes a trusted team and does not yet provide per-user roles or project permissions.
Atlas's supplied local Docker database is named atlas-db in Docker Desktop. It maps host port 5434 to PostgreSQL's internal port 5432. Option 1 in setup manages docker compose up -d --wait db on Atlas use; Docker Desktop must still be installed and running. Option 2 expects the user to run docker compose up -d db from the Atlas install folder first, then Atlas applies its schema but does not automatically restart Docker later.
The preferred local workflow is one Atlas install shared by many Codex projects. Atlas keeps one database in the install folder and separates project memory by project_id.
Install Atlas into a stable folder:
.\install-atlas.ps1 -InstallDir "$env:USERPROFILE\Atlas"
cd "$env:USERPROFILE\Atlas"
.\atlas setupThe installer copies program files, creates .venv, prepares the install-level work folder for Codex sandbox writes, and can add the Atlas folder to your user PATH. Setup still chooses storage and writes the install-level .env. SQLite storage is anchored to the install folder, so attached projects do not create their own Atlas databases.
Attach any Codex project:
atlas attach C:\path\to\my-project --project-name my-projectIf Atlas is not on PATH, use the full command:
C:\Users\Admin\Atlas\atlas attach C:\path\to\my-project --project-name my-projectatlas attach writes that project's .codex/config.toml and your global ~/.codex/config.toml with the shared Atlas MCP command and [mcp_servers.atlas.env] ATLAS_PROJECT_NAME. The MCP sends that project name to the API, so one running Atlas API can serve multiple projects without logging them all under the install folder name.
The older copy-or-clone-per-project workflow still works, but it is no longer the easiest path.
atlas setup
atlas attach C:\path\to\project --project-name project-name
atlas doctor
atlas stopatlas stop stops the local Atlas API listening on the configured ATLAS_API_URL port after confirming the health endpoint identifies as atlas-api. It is useful when you want to free port 8000 or force a fresh API start. Atlas does not currently auto-shut down after idle time; that is a possible later feature.
By default the dashboard and API only listen on your own computer (127.0.0.1). That is the safest setting.
Set a PIN (do this before opening it to other devices). Add this to the Atlas install folder's .env file:
ATLAS_DASHBOARD_PIN=123456When a PIN is set, the dashboard asks for it before showing any memory, and the API requires it on every request.
Let other devices on your network reach it. Add this to .env (only after the PIN is set):
ATLAS_API_HOST=0.0.0.0Then restart Atlas (quit and reopen Codex, or run atlas stop and open a fresh task). On your phone or another computer, open:
http://<your-computer-ip>:8000/dashboard/
Find your computer's IP with ipconfig (look for IPv4 Address). Only devices on the same Wi-Fi or network can reach it, and they need the PIN. Do not expose this on a public network. On your own computer you can still use http://127.0.0.1:8000/dashboard/.
Atlas is a local developer tool. The supported Build Week judge path is Windows 10/11 x64 with PowerShell and Codex Desktop. The architecture is intentionally portable to macOS and Linux because the backend is Python/FastAPI, the storage choices are SQLite or PostgreSQL, and the MCP server is launched through a Codex config command, but those platforms are not the primary packaged/demo path for this submission.
Platform notes:
- Windows 10/11 x64: primary tested and supported Build Week platform.
- Codex Desktop: required. It loads the Atlas MCP server from your global
~/.codex/config.toml. - PowerShell: used by the Windows installer and setup commands.
- Python 3.11 or newer: required for source setup; the installer creates Atlas's
.venvfrom an installed Python. - macOS/Linux: expected to work with Python 3.11+, but not packaged or fully tested for the Build Week judge path.
- Docker Desktop: optional, only needed for local Docker PostgreSQL.
- OpenAI API key: optional. Atlas runs without it in deterministic offline mode.
Judges do not need to rebuild a frontend or run a separate Node process. The dashboard is static JavaScript served by FastAPI. Follow Quick Start for Judges above, choose SQLite, and use the demo script. This tests the full product loop without Docker, cloud credentials, or an OpenAI API key.
Submission repository:
https://github.com/Ifeanyi-design/ATLAS
If the repository is public, include a license file. If it is private, Devpost requires sharing access with the event addresses listed in the submission form.
Atlas was built primarily through Codex collaboration during OpenAI Build Week, using GPT-5.6 model sessions for the main implementation work and later Codex sessions for reliability, documentation, and submission polish.
Codex accelerated the work in several places:
- Project planning: turning the initial product idea into a scoped v1 brief, phase plan, and demo spine.
- Backend implementation: building the FastAPI service, SQLAlchemy models, migrations, storage selection, and API routes.
- MCP integration: exposing Atlas as Codex tools through
log_decision,get_context,search,edit_memory,remove_memory, andoverride_conflict. - Retrieval and memory behavior: implementing project-scoped recall, fresh-session behavior, structured design-context capture, and conflict detection.
- Dashboard work: creating a dependency-free dashboard for decisions, conflicts, design context, storage state, and estimated context avoided.
- Reliability: adding setup recovery, doctor checks, Docker detection, cloud PostgreSQL support, SQLite fallback, and MCP startup fixes.
- Verification: writing and running focused tests across backend behavior, MCP contracts, storage modes, and restart scenarios.
Key human product decisions:
- Keep Atlas project-scoped by
project_id, with one local install able to attach many Codex projects. - Store decisions and reasons, not full transcripts.
- Treat conflicts as warnings with auditable overrides, not silent hard blocks.
- Support SQLite for frictionless testing and PostgreSQL + pgvector for production-like retrieval.
- Keep context-savings claims honest by showing estimates rather than claiming measured billing reductions.
GPT-5.6 and Codex contributed most directly to implementation speed, architecture iteration, bug diagnosis, test creation, and documentation. The final submission positioning is intentionally honest: Atlas is an MCP-enforced architectural memory and conflict-warning layer for Codex, not a universal background memory service.
The required Codex /feedback session ID is submitted in the Devpost form rather than committed into the public repository.
Atlas is meant to work alongside AGENTS.md, CLAUDE.md, and project notes, not replace them. Markdown files are still the right place for stable rules, setup instructions, coding conventions, and durable architecture notes.
The problem Atlas focuses on is the part that is easy to forget: decisions made during active development, the reason they were made, and later requests that contradict them. A markdown file only helps if a developer remembers to update it and if the next task reads the right section. Atlas stores material decisions as structured project memory, retrieves only the decisions relevant to the current request, and can warn when a new request conflicts with a prior choice.
In short: markdown is passive documentation; Atlas is an active decision layer for Codex.
If atlas is not recognized after installing, open a new PowerShell or Command Prompt first. Windows does not refresh PATH inside terminals that were already open before the installer updated the user environment.
If a new terminal still cannot find it, run the command by full path:
C:\Users\Admin\Atlas\atlas.cmd attach . --project-name atlas-judge-demoFor a custom install folder, replace C:\Users\Admin\Atlas with the folder chosen in the installer. After PATH refreshes, the shorter command works:
atlas attach . --project-name atlas-judge-demoAtlas is submitted to the OpenAI Build Week Developer Tools track. The core thesis is that long-running agentic development needs durable project decisions, scoped retrieval, and pre-work conflict warnings.
The repository documents:
- the build plan in docs/PLAN.md;
- progress history in docs/PROGRESS.md;
- the product brief in docs/PROJECT_BRIEF.md;
- the plain-English runbook in docs/RUNBOOK.md.
- Log a PostgreSQL architectural decision with
log_decision. - Start a different Codex task and call
get_contextwith a related prompt. - Ask to replace PostgreSQL with MongoDB; show the conflict and prior reason.
- Call
search("PostgreSQL")for explicit recall. - Log a UI decision with
Design context: {...}and show design-context injection. - Call
get_context(..., fresh_session=true)and show no injected decisions. - Open the dashboard and show timeline, conflict, design context, storage state, and estimated context avoided.
For the polished Build Week recording, use the three-minute flow above: decision capture, fresh-task recall, conflict warning, search, fresh-session mode, and dashboard evidence.
backend/- FastAPI service, SQLAlchemy models, migrations, services, scripts, and tests.mcp_server/- Atlas MCP tool server.dashboard/- dependency-free dashboard served by FastAPI.docs/- product brief, implementation plan, runbook, and progress log.infra/- local PostgreSQL/pgvector provisioning.
This project is intended to be published with the repository license file included. Devpost allows public repositories when they include relevant licensing, or private repositories shared with the required event addresses.