Skip to content

Quick Start

Jump to bottom
idapixl edited this page Jul 30, 2026 · 4 revisions

Quick Start

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

1. Create a workspace

npm install @fozikio/cortex-engine
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 59 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. Enable more tools (optional)

All 59 tools ship inside the engine — there is nothing extra to install. A 12-tool core set is active by default; enable the rest per-namespace in your config.

npx fozikio tools     # list every tool by category
npx fozikio config    # view or edit which tools are active

That's how you get thread_create, journal_write, dream, and the rest.

The old @fozikio/tools-* npm packages are deprecated — they were absorbed into core at v1.0.0. Don't install them.

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