Skip to main content
ACE3 LogoACE3

Getting Started with ACE

Cognitive infrastructure for AI systems — set up in 5 minutes

What is ACE?
Persistent memory that makes your AI smarter

ACE (Adaptive Context Engine) gives your AI permanent memory across all sessions. ACE remembers decisions, learns from problems, and applies patterns automatically — across every tool and conversation.

Key insight: ACE isn't for humans to track tasks - it's for AI to learn from your codebase. When your AI encounters a problem, it checks ACE first. When you make a decision, your AI remembers it.

Plans

Describe what you want to build. AI creates structured memories with relationships - your AI assistant now has full project context.

Knowledge Graph

Your AI traverses connections to find context you didn't know you needed. Trace problems to root causes automatically.

10 Entity Types Your AI Understands:

Issues
Decisions
Work Logs
Architecture
Best Practices
Patterns
Tags
Relationships
Generic Memories
Plans
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 - free forever, no credit card required

Quick Start (5 minutes)
Get ACE running in 5 steps and connect to the dashboard
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

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 and MCP is auto-configured for Claude Code.

Headless/CI/Docker? Use non-interactive login:

Step 3b: Initialize your database

The init wizard will:

  1. Configure your database - Cloud (Neon, Supabase, AWS) or local PostgreSQL
  2. Create schema - Set up all required tables automatically
  3. Create default namespace - Your first workspace, ready to use
  4. Set up AI IDE integration - Configures MCP for Claude, Cursor, and other AI tools
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 and auto-updates when ACE is upgraded
  • • Run ace start each session (after reboot)
  • • Use ace stop to stop the server

Keeping Your Database Schema Updated

When you update ACE to a new version, your database schema may need updating too. ACE handles this automatically in most cases:

  • • Automatic: Schema updates run automatically when ace start connects to your database
  • • CLI: Run ace migrate to manually apply pending migrations
  • • Dashboard: Go to Database page and click "Update Schema" if pending migrations are shown

Verify the server is running:

5

Connect to Dashboard

Link your local ACE server to the ace3-ai.com dashboard for visual management of your memories, knowledge graph, and team settings.

What this does:

  • Creates an API key linking your local server to the cloud dashboard
  • Enables the dashboard at ace3-ai.com/dashboard to query your local data
  • Your data stays on your machine — the dashboard connects to your server

Verify the connection by visiting your Dashboard.

Try It Out
Create your first memory to verify everything works

Test ACE by tracking an issue. With the server running, your AI (or you) can execute:

You should receive a JSON response with the created issue:

Your AI can now find this and similar issues:

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:

Schema outdated after ACE update

After upgrading ACE, your database schema may need updating. This usually happens automatically on ace start, but you can also run it manually:

Or use the Update Schema button on the Database dashboard page.

Dashboard shows "Connect your database" after CLI update

Cause: Updating the ACE CLI can occasionally reset your local config file, losing the database connection string.

Fix: Re-run ace init and re-enter your PostgreSQL connection string. Your data is safe in your database — this only restores the connection.

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 Plans - Generate complete project plans instantly with the Plans 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

Plans

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 Plans

Generate project plans with AI assistance

Need help? Check the documentation or contact support