Claude Code Integration

Use ACE with Claude Code - CLI tool and IDE extensions with REST API access

What is Claude Code?

Anthropic's AI coding assistant - CLI tool and IDE extensions

Claude Code is Anthropic's AI coding assistant available as a CLI tool and IDE extensions. It can execute bash commands on your local machine, making it perfect for calling ACE's REST API to store and retrieve memories.

How It Works:

Claude Code can execute bash/curl commands on your local machine. Simply tell Claude to store or recall information, and it will use curl to call ACE's REST API at localhost:7777.

Universal API

Works with all AI CLIs

Local-First

Runs on localhost:7777

JWT Auth

Secure token-based auth

Prerequisites

What you'll need

Claude Code

CLI or IDE extension installed

ACE3 Installed

Install with: npm install -g @ace3-memory/ace

ACE3 Account

API Keys (Optional)

Configure OpenAI key for semantic search. Learn about BYOK →

Setup Instructions

Get started in 3 steps

Install & Login to ACE3

Install ACE3 and authenticate:

# Install ACE3 (requires Node.js 18+)
npm install -g @ace3-memory/ace

# Login (opens browser for OAuth)
ace login

# Configure database
ace init

# Start the server
ace start

The ace login command opens your browser to authenticate. Your token is saved automatically.

Test the Connection

Verify ACE is accessible:

curl http://localhost:7777/health

Should return: {"status": "healthy", "service": "ACE Universal Server"}

⚙️ ACE Server URL

Where is your ACE server running?

💻 Local Development

Running ACE on your machine with ace start

curl http://localhost:7777/health

☁️ Cloud / On-Premises

ACE deployed to your infrastructure

curl https://ace.yourdomain.com/health

All tiers can run anywhere. Tiers only differ by limits (namespaces, members, memories).

💡 Pro Tip: In all examples below, replace http://localhost:7777 with your actual server URL from above.

Usage Examples

Common operations with Claude Code

Note: Replace {YOUR_NAMESPACE} with your namespace from the dashboard and {YOUR_TOKEN} with your JWT token from ~/.ace/config.json

Store Generic Memory

Save unstructured information to ACE:

curl -X POST http://localhost:7777/api/v1/{YOUR_NAMESPACE}/generic-memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Project uses Next.js 14 with App Router and PostgreSQL database",
    "context": "framework-decision",
    "tags": ["technical"]
  }'

List and Filter Issues

Query issues by status and limit results:

curl "http://localhost:7777/api/v1/{YOUR_NAMESPACE}/issues?status=open&limit=10" \
  -H "Authorization: Bearer {YOUR_TOKEN}"

Track an Issue

Log bugs and problems:

curl -X POST http://localhost:7777/api/v1/{YOUR_NAMESPACE}/issues \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Memory leak in event listeners",
    "description": "Listeners not cleaned up properly",
    "severity": "high",
    "priority": "P1"
  }'

Track a Decision

Record architectural decisions:

curl -X POST http://localhost:7777/api/v1/{YOUR_NAMESPACE}/decisions \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "Use PostgreSQL for production",
    "rationale": "Better performance and reliability",
    "alternatives": ["MongoDB", "MySQL"]
  }'

Generate Project Plan with AI Builder

Use AI to create complete project plans with all entities and relationships:

curl -X POST http://localhost:7777/api/v1/{YOUR_NAMESPACE}/plans/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "E-commerce Platform",
    "description": "Build a modern e-commerce platform with React, Node.js, and PostgreSQL"
  }'

Uses your configured AI provider. Atomically creates issues, decisions, architecture, and relationships in one API call.

Create Knowledge Graph Relationship

Link entities together in the knowledge graph:

curl -X POST http://localhost:7777/api/v1/{YOUR_NAMESPACE}/relationships \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "decision",
    "source_id": 5,
    "target_type": "issue",
    "target_id": 12,
    "relationship_type": "resolves",
    "metadata": "{\"context\": \"architectural decision resolved the bug\"}"
  }'

Traverse Knowledge Graph

Explore relationships up to 4 levels deep:

curl -X GET "http://localhost:7777/api/v1/{YOUR_NAMESPACE}/relationships/traverse/decision/5?max_depth=3" \
  -H "Content-Type: application/json"

💡 Optional: Environment Variables for Convenience

If you prefer, you can set environment variables to avoid repeating values:

export ACE_NAMESPACE="your-namespace"
export ACE_JWT_TOKEN="$(cat ~/.ace/config.json | jq -r '.auth.token')"

Then use $ACE_NAMESPACE and $ACE_JWT_TOKEN in commands:

curl http://localhost:7777/api/v1/$ACE_NAMESPACE/issues \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

How Claude Code Uses ACE

Natural language to API calls

Simply ask Claude to remember or recall information in natural language, and it will execute the appropriate curl commands to interact with ACE.

YOU SAY:

"Create a decision to use PostgreSQL for our database"

↓

CLAUDE EXECUTES:

curl -X POST http://localhost:7777/api/v1/{YOUR_NAMESPACE}/decisions \
  -H "Content-Type: application/json" \
  -d '{"decision": "Use PostgreSQL", "rationale": "Better performance and reliability"}'

YOU SAY:

"What database are we using?"

↓

CLAUDE EXECUTES:

curl "http://localhost:7777/api/v1/{YOUR_NAMESPACE}/decisions?limit=10" \
  -H "Content-Type: application/json"

↓

CLAUDE RESPONDS:

"Based on the decisions, we're using PostgreSQL for better performance and reliability."

YOU SAY:

"Generate a complete project plan for building an e-commerce platform"

↓

CLAUDE EXECUTES:

curl -X POST http://localhost:7777/api/v1/{YOUR_NAMESPACE}/plans/bulk \
  -H "Content-Type: application/json" \
  -d '{"project_name": "E-commerce Platform", "description": "...", "ai_provider": "anthropic"}'

↓

CLAUDE RESPONDS:

"I've created a complete project plan with 15 issues, 8 decisions, 12 architecture components, and 20 relationships in your knowledge graph."

💬 Working with ACE Memory

Natural language commands for seamless AI-to-memory integration

ACE Adapts to Your Workflow

ACE provides 9 structured entity types plus unlimited generic memories - use whichever fits your needs. There are no restrictions on how you organize information. Store architectural decisions, track bugs, log daily work, document patterns, or create free-form memories. ACE's knowledge graph connects everything together, regardless of type.

STRUCTURED ENTITIES

• Decisions - Architectural choices with rationale
• Issues - Bugs, features, technical debt
• Work Logs - Session tracking, daily progress
• Architecture - System components, services
• Patterns - Reusable solutions, conventions
• Best Practices - Guidelines, standards

FLEXIBLE STORAGE

• Generic Memories - Any unstructured data
• Tags - Custom categorization
• Relationships - 12 link types between entities
• Namespaces - Project/feature/client isolation
• Semantic Search - Find by meaning, not keywords
• Knowledge Graph - Traverse connections

Example Prompts by Category

Use these phrases with any AI tool (Claude Code, ChatGPT, Cursor, Windsurf) to interact with ACE:

📋 Architectural Decisions

Track technical choices with context and alternatives considered:

"Log this decision in ACE: Use PostgreSQL for the database because we need ACID compliance"

"Record a decision - we chose JWT over sessions for auth, alternatives were OAuth2 and API keys"

"Track the architectural decision about our microservices boundaries"

🐛 Issues & Technical Debt

Track bugs, features, and improvements with priority and status:

"Track this as a P1 issue in ACE: Memory leak in WebSocket handlers causing server crashes"

"Log a feature request: Users want dark mode support"

"Create a technical debt issue for the legacy auth code that needs refactoring"

📝 Work Logs & Sessions

Track completed work, time spent, and link to related decisions/issues:

"Record today's work in ACE - I fixed the auth bug and updated the docs"

"Log this session: refactored the payment module, took about 3 hours"

"Create a work log and link it to decision 1003 and issue 45"

🏗️ Architecture & Patterns

Document system components, services, and reusable solutions:

"Document the API Gateway architecture - it handles auth, rate limiting, and routing"

"Add a pattern for error handling - we use Result types instead of exceptions"

"Record a best practice: All API responses must include request IDs for tracing"

💾 Generic Memories

Store anything that doesn't fit structured types - ACE has no limits on what you can remember:

"Remember this in ACE: The client prefers communication via Slack, not email"

"Store this context: Project deadline is March 15th, budget is £50k"

"Save this for later: The API rate limit is 1000 requests per minute"

🔗 Knowledge Graph & Relationships

Connect entities to build a navigable knowledge graph:

"Link this work log to decision 1003"

"Connect issue 45 to the database architecture - it implements the caching layer"

"Create a relationship: decision 12 supersedes decision 8"

🏷️ Tags & Organization

Organize with custom tags - create your own taxonomy:

"What tags are available in ACE?"

"Create a tag called v3.0.15 for this release"

"Tag this decision with frontend and performance"

🔍 Recall & Search

Find information using natural language - ACE uses semantic search:

"What decisions have we made about authentication?"

"Show me all open P1 issues"

"Get context from ACE about the payment system architecture"

"Search ACE for anything related to database performance"

💡 Best Practices

• Be specific: "Log a decision about X" is clearer than "remember this"
• Include rationale: "We chose X because Y" provides valuable context for future reference
• Request IDs: "What ID was that decision?" so you can link related work later
• Check tags first: Ask "What tags exist?" before tagging to avoid validation errors
• Build connections: "Log this and link to decision 42" creates a navigable knowledge graph
• Use the right type: Structured entities (decisions, issues) are searchable by field; generic memories are free-form

ℹ️ No Limits on Memory Types

ACE doesn't restrict how you use memory types. Store project requirements as decisions, use issues for meeting notes, or keep everything in generic memories - whatever works for your workflow. The 9 entity types exist to provide useful structure, but you're free to use ACE however you need. All entities support tagging, relationships, and semantic search regardless of type.

🚀 Automatic Session Tracking

Never lose track of your coding sessions again

What is Automatic Session Tracking?

Every time your Claude Code conversation reaches the context limit and compacts, ACE automatically creates a work log with session statistics - completely hands-free. No manual tracking needed!

How It Works:

You work on your project with Claude Code

When conversation hits context limit, Claude compacts the history

PreCompact hook automatically triggers before compaction

Hook extracts session data: file edits, reads, writes, bash commands

Work log created in ACE automatically with stats and tags

View in dashboard, link to decisions/issues, build knowledge graph

Data Captured Automatically:

Number of file edits

Number of file reads

New files created

Bash commands run

Session timestamp

Session ID

One-Time Setup Instructions:

Download the Hook Script

Download and install the PreCompact hook:

# Create hooks directory
mkdir -p ~/.config/claude-code/hooks

# Download the hook script
curl -fsSL https://ace3-ai.com/hooks/precompact.sh \
  -o ~/.config/claude-code/hooks/ace-precompact.sh

# Make it executable
chmod +x ~/.config/claude-code/hooks/ace-precompact.sh

Configure Claude Code

Add hook configuration to your project's .claude/settings.local.json:

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "~/.config/claude-code/hooks/ace-precompact.sh"
          }
        ]
      }
    ]
  }
}

Or use the /hooks command in Claude Code to configure graphically.

Create Required Tags

Create tags in ACE for the hook to use:

# Create auto-tracking tags (one-time setup)
curl -X POST http://localhost:7777/api/v1/tags \
  -H "Authorization: Bearer $(cat ~/.ace/config.json | jq -r '.auth.token')" \
  -H "Content-Type: application/json" \
  -d '{"name": "auto-tracked", "description": "Automatically tracked", "category": "automation"}'

# Repeat for: session-compact, ai-assisted, claude-code

Or create them in the dashboard at ace3-ai.com/dashboard

✓

Done! It's Automatic Now

The hook runs automatically when conversations compact. No further action needed!

💡 Pro Tips

• Work logs appear automatically in your dashboard with "auto-tracked" tag
• Link them to decisions/issues manually later for complete context
• View session history in the knowledge graph to see your development timeline
• Perfect for teams: Everyone's sessions tracked automatically for retrospectives
• Hook logs to system console - check with: log show --predicate 'eventMessage contains "ACE-PreCompact"'

ℹ️ Technical Details

• Trigger: Fires when Claude Code hits context limit (before compaction)
• Authentication: Uses token from ~/.ace/config.json automatically
• Namespace: Uses ACE_NAMESPACE env var (must be set)
• Data Source: Extracts from Claude Code transcript file
• Performance: Hook runs in background, doesn't slow down compaction
• Privacy: Only metadata captured (counts), not actual code content

Who Needs to Set This Up?

Each user sets it up individually on their local machine. This is a client-side hook that runs in your Claude Code CLI environment. Once configured, it works automatically for all your coding sessions. Team admins don't need to do anything - each developer installs it themselves if they want automatic tracking.

Troubleshooting

Common issues and solutions

401 Unauthorized

Re-authenticate with ACE3:

ace login  # Opens browser to re-authenticate

Connection Refused

Verify ACE server is running:

curl http://localhost:7777/health

If not running, start it with:

ace start

Token Expired

ace login

PreCompact Hook Not Creating Work Logs

Check hook logs for errors:

log show --predicate 'eventMessage contains "ACE-PreCompact"' --last 5m

Common issues:

• Hook script not executable: chmod +x ~/.config/claude-code/hooks/ace-precompact.sh
• Tags not created: Create tags in dashboard or via API first
• ACE server not running: Start with ace start
• Token missing: Check ~/.ace/config.json exists

Test Hook Manually

Test hook without waiting for compaction:

echo '{"session_id":"test","transcript_path":"/tmp/test.txt","trigger":"auto"}' | ~/.config/claude-code/hooks/ace-precompact.sh

Tag Does Not Exist Error

When logging with tags that don't exist:

{"error": "Invalid tags: tags must exist in global tag system"}

Solution: Create the tag first, then retry:

# Ask your AI: "What tags are available in ACE?"
# Then: "Create a tag called my-new-tag"
# Then retry your original command

Namespace Not Found

If you get "namespace not found":

# Check your namespace in the dashboard
# Or ask: "What namespace am I using?"
# Verify ACE_NAMESPACE env var is set correctly

Quota Exceeded

Hit your tier limits:

# Check limits: visit ace3-ai.com/dashboard/billing
# Starter: 100 memories, 50 API calls/day
# Developer: 2,500 memories, 500 API calls/day
# Pro+: Unlimited