Fozikio

FAQ

Does this work with Cursor, Windsurf, or other MCP clients?

Yes. cortex-engine is a standard MCP server — any MCP-compatible client works. Claude Code, Cursor, Windsurf, Zed, and custom agents all connect the same way: via the .mcp.json config file or by manually adding the server to your client's MCP settings.

The generated .mcp.json from npx fozikio init works with Claude Code automatically. For other clients, copy the server config into your client's settings.

What if Ollama isn't installed?

cortex-engine includes built-in embeddings (all-MiniLM-L6-v2) that work without any external services. This is the default. Ollama is optional — it provides higher-quality embeddings but isn't required to get started.

To use built-in embeddings explicitly:

npx fozikio config --embed built-in

Can I migrate from SQLite to Firestore?

There's no automated migration tool yet. The practical options:

  • Re-observe key knowledge — use query() to retrieve important observations from SQLite, then observe() them into the Firestore-backed store
  • Start fresh — for most personal agents, letting the agent rebuild through use is simpler than migrating
  • Custom script — read from .fozikio/cortex.db and write to Firestore via the cortex API

For large stores, digest() can re-ingest content in batches efficiently.

How many agents can I run?

Unlimited. Agents are isolated via namespaces, so you can add as many as you need:

npx fozikio agent add researcher
npx fozikio agent add writer
npx fozikio agent add trader
npx fozikio agent add archivist

Each namespace is cheap — it's just a partition in the same SQLite file or Firestore database.

What LLMs does cortex-engine support?

Any LLM you can run or call. The agent_invoke() tool supports:

  • Ollama — free, local, any model (Llama, Mistral, Qwen, DeepSeek, etc.)
  • Gemini — Google's Gemini models via API
  • DeepSeek — DeepSeek models via API
  • Hugging Face — any HF inference endpoint
  • OpenRouter — unified API for hundreds of models
  • OpenAI — GPT models via API
  • Any OpenAI-compatible API

The MCP server itself is LLM-agnostic — it works as a tool provider regardless of which model your client uses.

Does dream() run automatically?

No. dream() is triggered manually or via a scheduled task. It's intentionally explicit — consolidation takes time and changes the memory graph, so you control when it runs.

Run it periodically:

npx fozikio maintain fix   # CLI equivalent of dream()

Or set up a cron job to run it nightly. The sleep_pressure() tool tells you how much unprocessed memory has accumulated and whether it's time to consolidate.

How is this different from just saving chat history?

Chat history is a flat, unsearchable log. cortex-engine is a semantic graph with retrieval, belief tracking, and consolidation.

Key differences:

  • Semantic search — query("authentication approach") finds relevant memories even if they don't use those exact words
  • Belief tracking — positions are held explicitly and updated when contradicted, not silently overwritten
  • Consolidation — dream() clusters observations into abstractions, so expertise emerges from accumulated experience
  • Graph structure — memories are connected, so wander() and surface() can find non-obvious connections
  • Cross-session continuity — memories persist across sessions, models, and runtimes

Is there a hosted version?

Not yet. cortex-engine is self-hosted — you run it locally or deploy it to Cloud Run / any Node.js host.

A hosted option is on the roadmap. Follow github.com/Fozikio/cortex-engine or the project board for updates.

What's the difference between observe() and believe()?

  • observe() — a fact or finding. Something that happened or something you learned. "The API uses JWT tokens with 1-hour expiry."
  • believe() — a position or stance. Something the agent holds as a conclusion. "We should use PostgreSQL for this project."

Beliefs have contradiction tracking — if new evidence contradicts a belief, cortex-engine flags it. observe() doesn't have this. Use the typed tools (believe, wonder, speculate) instead of stuffing everything into observe().

What's the difference between query() and recall()?

  • query(question) — semantic search across all memories. Returns the most relevant nodes by meaning and salience. Use this for finding what you know about a topic.
  • recall(topic?) — returns recent observations in reverse chronological order. Use this to review what was captured in the current session.

How do I report a bug or request a feature?

GitHub Issues — check existing issues first.

For questions and discussion: GitHub Discussions or r/fozikio.