Fozikio

Getting Started

Fozikio builds open-source infrastructure for AI agents with persistent memory. The core package is @fozikio/cortex-engine — an npm library that gives any AI agent semantic memory, belief tracking, and goal-directed cognition via 27 MCP tools.

Prerequisites

  • Node.js 20+ (Node 18 works but 20 is recommended)
  • Ollama (optional) — for local embeddings. Built-in embeddings work without it
  • An MCP-compatible client: Claude Code, Cursor, Windsurf, or any MCP client

1. Install

npm install @fozikio/cortex-engine

2. Initialize a workspace

npx fozikio init my-agent
cd my-agent

This creates:

  • .fozikio/ — agent identity, config, and local memory store
  • .fozikio/agent.yaml — storage, embeddings, and LLM provider config
  • .mcp.json — MCP server config auto-detected by Claude Code and Cursor
  • CLAUDE.md / AGENTS.md — tool reference injected into your agent's context

3. Start the MCP server

npx fozikio serve

The server runs over stdio. Your MCP client connects via .mcp.json automatically.

Manual MCP config — if your client doesn't auto-detect .mcp.json:

{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": ["@fozikio/cortex-engine"]
    }
  }
}

4. Connect your AI client

Claude Code auto-detects .mcp.json in your project root — no extra steps.

Cursor / Windsurf — add the MCP config to your client settings under MCP Servers.

Other clients — use the JSON snippet above in whatever format your client expects.

5. Your first memory round-trip

Once connected, your agent has 27 cognitive tools. The basics:

# Store a fact
observe("The API uses JWT tokens with 1-hour expiry")

# Retrieve by meaning — not exact string match
query("authentication approach")
# → [{ content: "The API uses JWT tokens...", salience: 0.91 }]

# Record a question
wonder("Should we switch to session-based auth?")

# See recent observations
recall()

# Consolidate into long-term memory
dream()

Read before you write — query() first, then observe(). The tool descriptions guide everything else.

6. Multi-agent setup

Add more agents with isolated memory namespaces:

npx fozikio agent add researcher --description "Research agent"
npx fozikio agent add writer --description "Writing agent"
npx fozikio agent generate-mcp   # rewrites .mcp.json with scoped servers

Each agent has completely independent memory. See Multi-Agent for details.

Configuration

Edit .fozikio/agent.yaml or use the CLI:

npx fozikio config --store sqlite --embed ollama --llm ollama

| Setting | Options | Default | |---------|---------|---------| | Storage | sqlite, firestore | sqlite | | Embeddings | built-in, ollama, vertex, openai | built-in | | LLM | ollama, gemini, anthropic, openai, openrouter | ollama |

Built-in embeddings work with zero configuration — no Ollama, no API keys needed. For higher quality embeddings, install Ollama and run:

ollama pull nomic-embed-text
npx fozikio config --embed ollama

Useful CLI commands

npx fozikio serve              # start MCP server
npx fozikio health             # memory health report
npx fozikio vitals             # behavioral vitals
npx fozikio wander             # walk through the memory graph
npx fozikio wander --from "auth"  # seeded walk from a topic
npx fozikio maintain fix       # scan and repair data issues
npx fozikio report             # weekly quality report

Next Steps

  • Architecture — Storage, embeddings, FSRS, dream consolidation, and graph retrieval
  • Multi-Agent — Isolated namespaces, agent dispatch, shared workspaces
  • Plugins — Add threads, journals, content pipelines, and more
  • API Reference — All 27+ MCP tools documented
  • Deployment — SQLite for dev, Firestore + Cloud Run for production