Python Quickstart

This guide gets you from zero to working memory in under 5 minutes.

Prerequisites

• Python 3.9+
• A CortexDB instance (cloud or self-hosted)
• An API key

Installation

pip install cortexdb

Initialize the Client

from cortexdb import Cortex

client = Cortex(
    base_url="http://localhost:3141",  # or your self-hosted URL
    api_key="your-api-key",
)

docker run -p 3141:3141 cortexdb/cortexdb:latest

Remember

Store a memory. CortexDB accepts content as a simple string, with optional metadata.

# Remember a message
client.remember(
    content="The user prefers dark mode and wants notifications disabled on weekends.",
    tenant_id="my-app",
    metadata={"source": "chat", "author": "user-123"},
)

# Remember a decision
client.remember(
    content="Team decided to use gRPC instead of REST for inter-service communication. Rationale: better performance for streaming use cases.",
    tenant_id="my-app",
    metadata={"source": "meeting-notes", "author": "tech-lead"},
)

For structured episodes with richer metadata, use ingest_episode:

from cortexdb import IngestEpisodeRequest

episode = IngestEpisodeRequest.from_dict({
    "content": "Refactored the auth middleware to support JWT and API key auth.",
    "type": "code",
    "source": "github",
    "actor": "alice",
    "metadata": {"repo": "acme/backend", "pr": 1234},
})
client.ingest_episode(episode)

Recall

Retrieve relevant memories using natural language queries.

# Simple recall
results = client.recall(
    query="What are the user's notification preferences?",
    tenant_id="my-app",
)

print(results.context)       # Synthesized context
print(results.confidence)    # Confidence score

Search

Search with filters for more control.

# Filter by source
results = client.search(
    query="Recent code changes to auth",
    source="github",
    tenant_id="my-app",
)

# Filter by time range
results = client.search(
    query="What architectural decisions were made?",
    episode_type="decision",
    time_range="30d",
    tenant_id="my-app",
)

Forget

Remove specific memories.

client.forget(
    query="old notification preferences",
    reason="User updated preferences",
    tenant_id="my-app",
)

Working with Entities

After ingestion, CortexDB automatically extracts entities and relationships.

# Get a specific entity with its relationships
entity = client.entity(
    entity_id="ent_xyz789",
    tenant_id="my-app",
)

print(f"Entity: {entity.name} ({entity.entity_type})")
for rel in entity.relationships:
    print(f"  --{rel.relationship}--> {rel.target_entity_id}")

Async Client

For async applications, use the async client.

from cortexdb import AsyncCortex
import asyncio

async def main():
    async with AsyncCortex(
        base_url="http://localhost:3141",
        api_key="your-api-key",
    ) as client:
        await client.remember(
            content="Async memory storage works great.",
            tenant_id="my-app",
        )

        results = await client.recall(
            query="async memory",
            tenant_id="my-app",
        )

        print(results.context)

asyncio.run(main())

Error Handling

from cortexdb import (
    CortexError,
    CortexAuthError,
    CortexRateLimitError,
    CortexAPIError,
)

try:
    results = client.recall(query="test", tenant_id="my-app")
except CortexAuthError:
    print("Invalid API key")
except CortexRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except CortexAPIError as e:
    print(f"API error [{e.status_code}]: {e.message}")
except CortexError as e:
    print(f"CortexDB error: {e}")

Next Steps