Skip to content

Installation

Jump to bottom
idapixl edited this page Mar 16, 2026 · 3 revisions

Installation

Prerequisites

  • Node.js 20+ (LTS recommended)

That's it. No cloud accounts needed for local use.

Option A: Scaffold a workspace (recommended)

npx fozikio init my-agent
cd my-agent

This creates a complete agent workspace with:

  • .fozikio/agent.yaml — identity and cortex configuration
  • .mcp.json — ready for Claude Code, Cursor, or any MCP client
  • CLAUDE.md — quick reference for Claude Code users
  • AGENTS.md — multi-agent roster
  • .claude/hooks/ — cognitive grounding hooks
  • .claude/skills/ — cortex memory skill
  • reflex-rules/ — safety guardrails (powered by @fozikio/reflex)

Init options

npx fozikio init my-agent --store sqlite      # default — local, no cloud needed
npx fozikio init my-agent --store firestore    # cloud — needs GCP project
npx fozikio init my-agent --embed built-in     # default — runs in-process
npx fozikio init my-agent --embed ollama       # local models via Ollama
npx fozikio init my-agent --embed vertex       # Google Cloud Vertex AI
npx fozikio init my-agent --obsidian           # add .obsidian/ config
npx fozikio init --here                        # scaffold into current directory

Option B: Add to an existing project

npm install cortex-engine@0.6.0

Then configure your MCP client — see MCP Integration.

Storage backends

SQLite (default)

Zero config. Creates a cortex.db file in your project directory. Works offline. Good for single-agent setups.

Firestore (cloud)

For remote access, multi-agent setups, or shared memory. Requires:

  1. A Google Cloud project with Firestore enabled
  2. Authentication (service account key or Application Default Credentials)
export GCP_PROJECT_ID="your-project-id"

# Option A: Service account key
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

# Option B: Application Default Credentials
gcloud auth application-default login

Embedding providers

Built-in (default)

Runs in-process using @huggingface/transformers (all-MiniLM-L6-v2, 384 dimensions). No external services needed. Downloads the model on first use (~23MB) with progress feedback. Cached for future starts.

Ollama (local)

For faster embeddings or custom models. Install Ollama, then:

ollama pull nomic-embed-text

Configure in agent.yaml:

cortex:
  default:
    embed: ollama

Vertex AI (cloud)

For production deployments on Google Cloud. Uses text-embedding-004 (768 dimensions). Requires GCP credentials.

Verify

Start the MCP server:

npx fozikio serve

Or check health:

npx fozikio health

Next Steps

Clone this wiki locally