Skip to main content
ACE3 LogoACE3
Public BetaWe're in Public Beta. Things may break. Please report issues via the Support tab.

Getting Started with ACE

Universal memory infrastructure for AI systems - Set up in 5 minutes

What is ACE?
The memory layer for AI agents

ACE (Adaptive Context Engine) is a PostgreSQL-powered memory infrastructure that gives AI systems the ability to remember and organize information across conversations.

AI-Assisted Plan Builder

Generate complete project plans in seconds. AI creates issues, decisions, architecture, and relationships automatically.

Knowledge Graph

Interactive graph with 10 relationship types. Trace issues to decisions, explore dependencies, and visualize connections.

9 Entity Types:

Issues
Decisions
Work Logs
Architecture
Best Practices
Patterns
Tags
Relationships
Generic Memories
Prerequisites
What you need before starting
1

Node.js 18 or higher

Check your version: node --version

Download from nodejs.org if needed

2

PostgreSQL Database

You'll need a PostgreSQL connection string. Options include:

  • Neon - Free tier, no credit card required (recommended)
  • Supabase - Free tier available
  • Local PostgreSQL - Install on your machine
  • AWS RDS / Google Cloud SQL - For production
3

ACE Account (Free)

Sign up at ace3-ai.com/signup - no credit card required for Starter tier

Quick Start (5 minutes)
Get ACE running in 5 steps
1

Get a PostgreSQL Database

ACE requires PostgreSQL for memory storage. We recommend Neon for the easiest setup.

Recommended: Neon (Free Tier)

  1. Visit neon.tech (no credit card required)
  2. Click "Sign Up" and create an account
  3. Click "Create a Project" and give it a name (e.g., "ace-memory")
  4. Copy your connection string from the dashboard

postgresql://user:password@ep-xxx.region.aws.neon.tech/dbname?sslmode=require

Neon Connection String Format:

postgresql://user:password@ep-xxx.region.aws.neon.tech/dbname?sslmode=require
2

Install ACE

Install ACE globally via npm. This downloads the compiled binary for your platform automatically.

What this does:

  • Installs the ace command globally
  • Auto-downloads the compiled binary for your OS (macOS, Linux, Windows)
  • Sets up the CLI for immediate use

Verify the installation:

3

Login and Initialize

Login to your ACE account and configure your database connection.

Step 3a: Login to ACE

This opens your browser to sign in. Your auth token is saved securely.

Step 3b: Initialize your database

The init wizard will ask:

  1. Cloud database - Paste your connection string from Neon, Supabase, etc.
  2. Local database - Enter host, port, database name, username, password
  3. Skip - Configure later via the dashboard Settings page
4

Start ACE Server

Start the ACE server to enable memory operations.

✅ ACE is now running!

  • • Server URL: http://localhost:7777
  • • Schema auto-initializes on first connection
  • • Press Ctrl+C to stop

Verify the server is running:

5

Configure AI Provider Keys (Optional)

Enable semantic search and AI Builder by adding your API keys.

Go to Dashboard → Settings and add your API keys:

OpenAI

Required for semantic search, also available for AI Builder

Anthropic

For AI Builder (Claude models)

Google

For AI Builder (Gemini models)

Keys are encrypted at rest. Learn more about BYOK →

Try It Out
Create your first memory to verify everything works

Test ACE by creating your first issue. With the server running, execute:

You should receive a JSON response with your created issue:

List all issues in your namespace:

Production Authentication

For production deployments, you'll need to include an API key or JWT token in your requests:

-H "Authorization: Bearer YOUR_API_KEY"

Generate an API key: ace api-key create --name "My Key"

Troubleshooting
Common issues and solutions

ace: command not found

The ACE CLI isn't in your PATH. Try:

  • Restart your terminal after installation
  • Run npm list -g @ace3-memory/ace to verify installation
  • Try reinstalling: npm install -g @ace3-memory/ace

Connection refused (localhost:7777)

ACE server isn't running. Start it with:

Database connection failed

Check your database connection string. Common issues:

  • Verify the connection string format is correct
  • Ensure the database server is running and accessible
  • Check firewall rules allow connections
  • Re-run ace init to reconfigure

Authentication failed

Your login session may have expired. Re-authenticate:

Dashboard shows "Connection Error" but ACE is running

This is usually a CORS issue. The ACE dashboard needs permission to connect to your server.

  • Local ACE: Update to latest version which includes ace3-ai.com in default CORS
  • Self-hosted ACE: Set the ACE_ALLOWED_ORIGINS environment variable:

For cloud deployments (AWS, GCP, etc.), add these origins to your environment configuration.

Pro Tips
  • Set up Passport early - Passport provides device-bound auth that never expires. Run ace passport create then ace passport link to avoid token refresh issues with AI tools
  • Enable Observer - Observer is AI monitoring AI - it catches errors, conflicts, and missed context before they become problems. Use via MCP or REST API
  • Namespaces isolate data - Use different namespaces for different projects (e.g., my-app, client-project)
  • Keep ACE running - Run ace start in a dedicated terminal tab, or use ace stop to stop the server when done
  • Connect your AI tools - ACE works with Claude Code, Cursor, VS Code, and more via MCP. See our MCP setup guides
  • View your data - Access the ACE Dashboard to see your memories, issues, and knowledge graph
  • Use AI Builder - Generate complete project plans instantly with the AI Builder feature
Passport Authentication

Device-bound authentication that never expires. Set up once, avoid token refresh issues forever

Observer (AI Monitoring AI)

Catch errors, conflicts, and missed context before they become problems. 2-way quality assurance

AI-Assisted Plan Builder

Generate complete project plans powered by your configured AI provider

Knowledge Graph

Visualize relationships between issues, decisions, and architecture with interactive graph

Next Steps
Continue your ACE journey

Set Up Passport

Device authentication that never expires - recommended first step

Enable Observer

AI monitoring AI - catch errors before they happen

Connect AI Tools

Set up MCP with Claude Code, Cursor, VS Code, and more

API Reference

Explore all available endpoints and features

Open Dashboard

View and manage your memories visually

Try AI Builder

Generate project plans with AI assistance

Need help? Check the documentation or contact support