Configuration

Configuration

agent.yaml

The agent manifest file declares identity and connections. Created by npx fozikio init:

agent:
  name: my-agent
  version: "1.0"

identity:
  profile: mind/profile.md
  session_state: state/session-state.md

agents: {}

cortex:
  default:
    store: sqlite         # sqlite (default) or firestore
    embed: built-in       # built-in, ollama, vertex, or openai
    primary: true

credentials:
  dir: credentials/
  encryption: none

Storage backends

Backend	Config	When to use
sqlite	Default, zero config	Local development, single-agent
firestore	Needs GCP project	Cloud deployments, multi-agent, shared memory

Embedding providers

Provider	Config	Speed	Requirements
built-in	Default	~200ms/embed	None (downloads model on first use)
ollama	Local server	~50ms/embed	Ollama + nomic-embed-text
vertex	Google Cloud	~100ms/embed	GCP project, credentials
openai	OpenAI API	~100ms/embed	API key

Environment Variables

Variable	Required	Default	Description
GCP_PROJECT_ID	If firestore	—	Google Cloud project ID
GOOGLE_APPLICATION_CREDENTIALS	If firestore/vertex	—	Path to service account JSON
CORTEX_API_TOKEN	If hosted	—	Auth token for HTTP API
OLLAMA_URL	If ollama	http://localhost:11434	Ollama server URL

Multi-Agent

Register agents with isolated namespaces:

npx fozikio agent add researcher --description "Research agent"
npx fozikio agent add trader --description "Trading signals"
npx fozikio agent generate-mcp    # writes .mcp.json with scoped servers

Or configure manually in agent.yaml:

agents:
  researcher:
    description: "Research agent"
    namespace: researcher
  trader:
    description: "Trading signals"
    namespace: trader

Firestore Setup

Collections

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

Indexes

For optimal query performance with Firestore, 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 service account access only:

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

Safety Rules (Reflex)

cortex-engine ships with @fozikio/reflex for safety guardrails. Rules are installed to reflex-rules/ during init.

Validate rules:

npx reflex validate reflex-rules

Test rules:

npx reflex test reflex-rules --event bash_command --command "rm -rf /"

Add custom rules by creating YAML files in reflex-rules/. See the reflex README for the rule format.

LLM Providers

cortex-engine needs an LLM for cognitive operations (dream, reflection, agent tasks). Configure in fozikio.json:

Provider	Config	Requirements
ollama	Default, local	Ollama + model installed
gemini	Google Cloud	GCP project, Vertex AI
openai	Universal adapter	Any OpenAI-compatible API key

The openai provider auto-detects your API key and configures the correct base URL for OpenAI, DeepSeek, Hugging Face, OpenRouter, Together AI, Fireworks, and local servers.

See the LLM Providers page for full configuration details.