Skip to content

Quick Start

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

Quick Start

Get cortex-engine running and make your first observations in 5 minutes.

1. Create a workspace

npm install cortex-engine@0.6.0
npx fozikio init my-agent
cd my-agent

This scaffolds everything: config, hooks, skills, safety rules, and MCP integration.

2. Connect your AI client

The init command creates a .mcp.json that works with Claude Code, Cursor, and other MCP clients. It's version-pinned and platform-aware — on Windows it automatically adds the cmd /c wrapper to prevent spawn npx ENOENT errors.

Open your project in Claude Code or Cursor. Cortex tools are available immediately.

3. Start using it

Your agent now has 25 cognitive tools. Try these:

> observe("I prefer TypeScript over JavaScript for backend work")
> observe("The API uses Hono on Cloud Run")
> query("what do I know about the tech stack?")
> believe("Hono is better than Express for serverless", 0.8)

4. Add plugins (optional)

Plugins add more tools. Install them and cortex auto-discovers them:

npm install @fozikio/tools-threads @fozikio/tools-journal

Now your agent also has thread_create, thread_update, journal_write, and more.

5. Check your safety rules

Your workspace includes reflex safety rules. Validate them:

npx reflex validate reflex-rules
npx reflex list reflex-rules

Test a rule:

npx reflex test reflex-rules --event bash_command --command "rm -rf /"
# → BLOCKED by destructive-commands rule

What happens under the hood

  • Storage: SQLite by default (zero config). Switch to Firestore for cloud deployments.
  • Embeddings: Built-in transformer model (runs in-process). Switch to Ollama or Vertex AI for faster/custom embeddings.
  • Memory: Observations are embedded and stored. Queries use cosine similarity for semantic search.
  • FSRS: Memories have strength that changes based on access patterns. Unused memories fade. Frequently accessed memories strengthen.
  • Dream: Periodic consolidation merges related observations, generates abstractions, and decays stale memories.

Multi-agent

npx fozikio agent add researcher --description "Research agent"
npx fozikio agent add trader --description "Trading signals"
npx fozikio agent generate-mcp

Each agent gets its own namespace with isolated memory. See Architecture for details.

CLI commands

npx fozikio init <name>         # scaffold a workspace
npx fozikio serve                # start the MCP server
npx fozikio health               # cortex health report
npx fozikio vitals               # behavioral metrics
npx fozikio wander               # walk through the memory graph
npx fozikio wander --from "auth" # seeded walk from a topic
npx fozikio anomalies            # detect unusual sessions
npx fozikio report               # weekly quality report
npx fozikio maintain fix         # repair data issues
npx fozikio agent list           # list registered agents

Next Steps

Clone this wiki locally