Configuration

Configuration

Environment Variables

Variable	Required	Default	Description
GCP_PROJECT_ID	Yes	—	Google Cloud project with Firestore
GOOGLE_APPLICATION_CREDENTIALS	Yes*	—	Path to service account JSON (*not needed on GCP)
CORTEX_API_TOKEN	For hosted	—	Auth token for HTTP API
EMBED_PROVIDER	No	vertex	Embedding provider: vertex or ollama
EMBED_MODEL	No	text-embedding-004	Embedding model name
OLLAMA_URL	If ollama	http://localhost:11434	Ollama server URL

agent.yaml

The agent manifest file declares identity and connections:

agent:
  name: MyAgent
  version: "1.0"

cortex:
  self:
    url: https://my-cortex.run.app    # or omit for local
    auth: CORTEX_API_TOKEN             # env var name
    primary: true

credentials:
  dir: credentials/
  manifest: credentials/credentials.yaml
  encryption: none

Firestore Setup

Collections

cortex-engine auto-creates collections on first use. No manual setup needed.

Indexes

For optimal query performance, create these composite indexes:

Collection: memories
  Fields: tags (Array) ASC, created_at DESC

Collection: memories
  Fields: type ASC, strength DESC

Collection: threads_v2
  Fields: status ASC, updated_at DESC

Security Rules

For production, lock down Firestore to only allow service account access:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false; // Service account bypasses rules
    }
  }
}

Plugin Configuration

Plugins are registered at initialization:

import { CortexEngine } from 'cortex-engine';
import { threadsPlugin } from '@fozikio/tools-threads';

const cortex = new CortexEngine({
  projectId: process.env.GCP_PROJECT_ID,
  plugins: [threadsPlugin],
});

No additional configuration needed — plugins use the cortex instance's Firestore connection.