Atlas

A Python semantic-memory framework with an optional 3D web app.

Atlas stores durable memories in SQLite, with optional LanceDB vector search and local embeddings. The Python package is the supported memory implementation. The React application, FastAPI service, CLI, workers, and MCP server are optional adapters over the same Python SDK.

Quick start

Requirements: Python 3.11 or newer and UV.

uv sync --extra cli
uv run atlas --help

The SDK runs without a server, frontend, worker, or Node process:

uv run python -c "from atlas_memory import Atlas; print(Atlas().list())"

Set TOKENROUTER_API_KEY or OPENROUTER_API_KEY before adding or updating memories. Read-only SQLite and FTS operations do not require a provider key.

Optional adapters

Install only the extras you need:

uv sync --extra server             # FastAPI HTTP service
uv sync --extra cli                # atlas command
uv sync --extra mcp                # atlas-mcp stdio server
uv sync --extra lancedb            # LanceDB vector store
uv sync --extra local-embeddings   # local Transformers embeddings

Start the supported HTTP service with:

uv run --extra server atlas-server

It listens on http://127.0.0.1:3001 by default. Set PORT, CORS_ORIGINS, ENGRAM_DB_PATH, and the provider variables for deployment.

Static web app

FastAPI serves the prebuilt optional React app from public/app/; it does not need a Node process at runtime. Open http://127.0.0.1:3001 after starting atlas-server. Rebuilding those static files is optional and uses Vite:

npm install
npm run dev:web

Vite runs on http://localhost:5174 and uses ATLAS_API_URL when the API is not at http://localhost:3001. Build the static app with npm run build:web.

CLI, workers, and MCP

uv run --extra cli atlas list --limit 20
uv run --extra lancedb --extra local-embeddings atlas-worker vector --once
uv run --extra mcp atlas-mcp

The MCP server keeps protocol output on stdout and diagnostics on stderr.

Configuration and data

SQLite is the source of truth. By default, ENGRAM_DB_PATH is ./engram.db. When vector search is enabled, preserve its LANCEDB_PATH directory alongside the SQLite database. The Python package source lives in src/atlas_memory/.

Deployment model

Atlas is Python-only. Start atlas-server for the HTTP API and optional static web app. The old Node backend, CLI, MCP server, workers, tests, and provider adapters have been removed. This is a clean-start release: do not reuse an older Neurogram SQLite or LanceDB directory.

License

MIT.

The optimized brain atlas is derived from the Human Reference Atlas v1.3 3D Male Allen Brain by the HuBMAP Consortium, licensed under CC BY 4.0.