Python SDK

ace3-memory

The official Python client for ACE3 - type-safe, async-ready, with Pydantic models

Installation

pip install ace3-memory

Requires Python 3.9+. Includes sync and async clients, Pydantic v2 models, and full type hints.

Quick Start

Connect and create your first memory in 3 lines

Synchronous Client

from ace3 import ACEClient

client = ACEClient(
    base_url="http://localhost:7777",
    token="your-jwt-token",
    namespace="my-project"
)

# Create a memory
memory = client.memories.create(
    title="PostgreSQL Connection Pooling",
    content="Use max_connections=100 for production",
    tags=["database", "performance"]
)
print(f"Created memory: {memory.id}")

# Search memories
results = client.search("database performance")
for r in results:
    print(f"  {r.title} (score: {r.score:.2f})")

Async Client

from ace3 import AsyncACEClient
import asyncio

async def main():
    client = AsyncACEClient(
        base_url="http://localhost:7777",
        token="your-jwt-token",
        namespace="my-project"
    )

    # All methods have async equivalents
    issues = await client.issues.list(status="open")
    for issue in issues:
        print(f"  [{issue.priority}] {issue.title}")

asyncio.run(main())

Authentication

# Option 1: JWT token
client = ACEClient(token="your-jwt-token", ...)

# Option 2: API key
client = ACEClient(api_key="ace_...", ...)

# Option 3: Environment variables (auto-detected)
# Set ACE_JWT_TOKEN or ACE_API_KEY
client = ACEClient(base_url="http://localhost:7777", namespace="my-project")

Resource Classes

Full CRUD for every entity type

client.memories

Generic memories - create, list, get, update, delete

client.issues

Issue tracking - with status, priority, severity filters

client.decisions

Architecture decisions - with rationale and alternatives

client.work_logs

Daily work logs - with tasks, hours, date filters

client.architecture

System architecture - components, layers, tech stack

client.best_practices

Coding standards - guidelines and conventions

client.patterns

Code patterns - reusable solutions and templates

client.relationships

Knowledge graph - create, traverse, query links

CRUD Example - Issues

# Create
issue = client.issues.create(
    title="Add OAuth2 support",
    description="Implement Google and GitHub OAuth",
    priority="P1",
    severity="high",
    tags=["auth", "feature"]
)

# List with filters
open_issues = client.issues.list(
    status="open",
    priority="P1",
    limit=10
)

# Get by ID
issue = client.issues.get(42)

# Update
client.issues.update(42, status="in_progress")

# Delete
client.issues.delete(42)

Pydantic Models

Type-safe responses with full IDE autocomplete

All API responses are parsed into Pydantic v2 models, giving you type safety, validation, and IDE autocomplete out of the box.

from ace3.models import Issue, Decision, Memory

# Responses are typed Pydantic models
issue: Issue = client.issues.get(42)
print(issue.title)        # str
print(issue.priority)     # Literal["P0","P1","P2","P3","P4"]
print(issue.created_at)   # datetime
print(issue.tags)         # list[str]

# Serialize to dict or JSON
issue_dict = issue.model_dump()
issue_json = issue.model_dump_json()

Search & Knowledge Graph

# Semantic search across all entities
results = client.search("database migration strategy")

# Hybrid search with custom weights
results = client.hybrid_search(
    query="auth service dependencies",
    semantic_weight=0.4,
    graph_weight=0.6
)

# Knowledge graph traversal
related = client.relationships.traverse(
    entity_type="decision",
    entity_id=5,
    max_depth=2
)

# Create a relationship
client.relationships.create(
    source_type="issue",
    source_id=42,
    target_type="decision",
    target_id=5,
    relationship_type="resolves"
)

Best Practices

Use Environment Variables

Set ACE_JWT_TOKEN and ACE_BASE_URL as environment variables to avoid hardcoding credentials.

Prefer Async in Web Apps

Use AsyncACEClient in FastAPI, Django async views, or any async Python application for better performance.

Type Hints Everywhere

The SDK is fully typed. Enable strict mypy or pyright for maximum safety.