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.