@fozikio/cortex-engine

@fozikio/cortex-engine

Persistent memory for AI agents. Open source, LLM-agnostic, works with any MCP client.

Star History

What It Does

Most AI agents forget everything when the session ends. cortex-engine fixes that — it gives agents a persistent memory layer that survives across sessions, models, and runtimes.

• Semantic memory — store and retrieve observations, beliefs, questions, and hypotheses as interconnected nodes
• Belief tracking — agents hold positions that update when new evidence contradicts them
• Two-phase dream consolidation — NREM compression (cluster, refine, create) + REM integration (connect, score, abstract) — modeled on biological sleep stages
• Goal-directed cognition — goal_set creates desired future states that generate forward prediction error, biasing consolidation and exploration toward what matters
• Neuroscience-grounded retrieval — GNN neighborhood aggregation, query-conditioned spreading activation, multi-anchor Thousand Brains voting, epistemic foraging
• Information geometry — locally-adaptive clustering thresholds that respect embedding space curvature, schema congruence scoring
• Graph health metrics — Fiedler value (algebraic connectivity) measures knowledge integration; PE saturation detection prevents identity model ossification
• Spaced repetition (FSRS) — interval-aware scheduling with consolidation-state-dependent decay profiles
• Embeddings — pluggable providers (built-in, OpenAI, Vertex AI, Ollama) — no external service required by default
• LLM-agnostic — pluggable LLM providers: Ollama (free/local), Gemini, Kimi (Moonshot AI), DeepSeek, Hugging Face, OpenRouter, OpenAI, or any OpenAI-compatible API
• Three storage backends — local SQLite (default), cloud Firestore, and JSON file (backup/migration). All share one CortexStore interface — see docs/storage-backends.md
• Atomic transactions — withTransaction(fn) primitive composes multi-step writes. SQLite uses BEGIN IMMEDIATE with a per-store mutex; Firestore uses runTransaction with a write-routing proxy. See docs/concurrency.md
• Migration tooling — fozikio migrate --from <url> --to <url> clones between any pair of backends. ID-preserving, checkpointed, resumable, fails-loud on schema mismatch
• Typed tool catalogue — every cognitive tool carries category + whenToUse + doNotUse metadata so LLMs disambiguate cleanly. Browse with fozikio tools or GET /tools. Auto-generated reference at docs/tools-reference.md
• Long-context dream consolidation — set strategy: long-context to run edge discovery and abstraction in a single large LLM pass instead of N² pairwise calls; surfaces transitive patterns and cross-domain connections that the sequential approach misses
• Agent dispatch — agent_invoke lets your agent spawn cheap, cortex-aware sub-tasks using any configured LLM. Knowledge compounds across sessions.
• MCP server — 60 cognitive tools (query, observe, believe, wander, dream, goal_set, agent_invoke, thread_create, journal_write, evolve, etc.) over the Model Context Protocol

The result: personality and expertise emerge from accumulated experience, not system prompts. An agent with 200 observations about distributed systems doesn't need to be told "you care about distributed systems." It just knows.

Works with Claude Code, Cursor, Windsurf, or any MCP-compatible client. Runs locally (SQLite) or in the cloud (Firestore + Cloud Run).

Security

The engine includes defense-in-depth protections for deployed environments:

• Timing-safe auth — REST server authentication uses crypto.timingSafeEqual to prevent timing side-channel attacks
• Plugin sandboxing — the plugin loader validates import paths against trusted directories, blocking loads from untrusted locations
• REST tool blocklist — destructive tools (forget, dream, evolve, resolve, thread_resolve) are blocked from the generic REST endpoint; they remain available via MCP for direct agent access
• SQLite injection prevention — namespace names are validated (alphanumeric only), LIMIT clauses are parameterized
• Secret leak prevention — config loader warns when API keys appear in config files instead of environment variables

Known advisories

npm install @fozikio/cortex-engine currently reports 3 moderate advisories. All three are the same upstream issue counted at three levels of one dependency chain, and none are reachable in this package:

@fozikio/cortex-engine
└── @modelcontextprotocol/sdk@1.29.0   (latest)
    └── @hono/node-server ^1.19.9      ← GHSA-frvp-7c67-39w9

What it is: path traversal in @hono/node-server's serve-static middleware on Windows, via an encoded backslash (%5C).

Why it isn't fixed: the advisory's first patched version is 2.0.5 — a major-version bump the MCP SDK has not taken. @modelcontextprotocol/sdk@1.29.0 is the current latest and still pins ^1.19.9, so there is no remediation available downstream. Forcing 2.x via an override would break the SDK's expected API.

Why it doesn't affect you: cortex-engine never imports hono. @hono/node-server is pulled in only as a transitive dependency of the MCP SDK, and the MCP server here runs over stdio transport, which never mounts serve-static. The dashboard's static file serving is our own implementation (src/rest/server.ts), which resolves paths and verifies containment with path.relative before reading — explicitly handling the Windows backslash case this advisory describes.

This will clear on its own once the MCP SDK adopts @hono/node-server 2.x. Until then, npm audit noise from this chain is expected and safe to ignore.

Architecture

Module	Role
core	Foundational types, config, and shared utilities
engines	Cognitive processing: memory consolidation, FSRS, graph traversal
stores	Persistence layer — SQLite (local), Firestore (cloud), JSON (backup/migration). All implement the shared CortexStore interface
tools	All 60 cognitive tool implementations (one file per tool)
mcp	MCP server, tool registry, and plugin loader
cognitive	Higher-order cognitive operations (dream, wander, validate)
triggers	Scheduled and event-driven triggers
bridges	Adapters for external services and APIs
providers	Embedding and LLM provider implementations
bin	Entry points: serve.js (HTTP + MCP), cli.js (admin CLI)
public	Built-in web dashboard (served automatically with --rest)

Quick Start

npm install @fozikio/cortex-engine
npx fozikio init my-agent
cd my-agent
npx fozikio serve   # starts MCP server

Your agent now has 60 cognitive tools. The generated .mcp.json is version-pinned and platform-aware (Windows cmd /c wrapper handled automatically).

See the Quick Start guide for the full 5-minute setup.

Multi-Agent

npx fozikio agent add researcher --description "Research agent"
npx fozikio agent add trader --description "Trading signals"
npx fozikio agent generate-mcp   # writes .mcp.json with scoped servers

Each agent gets isolated memory via namespaces. See the Architecture section for details.

Agent-First Setup

The fastest path: open an AI agent in an empty directory and say "set up a cortex workspace." The agent runs npx fozikio init, reads the generated files, and is immediately productive. See the Agent-First Setup guide for the full walkthrough.

Dashboard

cortex-engine ships with a built-in web dashboard. Start the REST server and open the URL in your browser:

npx fozikio serve --rest --port 3000
# open http://localhost:3000

The dashboard shows your agent's stats, threads, ops log, memories, concepts, and observations — no separate install required. It auto-detects its API from the same origin it's served from.

If auth is enabled (CORTEX_API_TOKEN), the dashboard loads without auth but API calls require a token. Set it via localStorage:

localStorage.setItem("cortex-settings", JSON.stringify({ token: "your-token" }));

Source: fozikio-dashboard

CLI

Run fozikio with no arguments for an interactive session — a prompt with tab completion, history, and a filterable command palette on an empty enter:

  fozikio 1.3.0
  ● ollama  ● nli

  enter a command · empty enter to browse · ? help · exit quit

fozikio ›

Or use it directly:

npx fozikio doctor                         # diagnose the install, with fixes
npx fozikio dashboard                      # live service and memory view
npx fozikio up                             # start every service, wait until ready
npx fozikio status                         # service status (exit 1 if unhealthy)
npx fozikio down                           # stop every service
npx fozikio serve                          # start MCP server

Services. The default setup (--embed ollama --llm ollama, plus NLI adjudication) depends on two background daemons: ollama on :11434 and the NLI cross-encoder on :11435. When either stops answering, every semantic tool — query, observe, wonder, dream — fails while ops, threads and journal keep working, so the failure is easy to miss. fozikio supervises both:

npx fozikio service start nli              # start detached, wait for the probe
npx fozikio service status                 # per-service state
npx fozikio service logs ollama --lines 50 # tail ~/.fozikio/logs/
npx fozikio service restart ollama
npx fozikio up --watch                     # restart on failure, with backoff

A service counts as up when its HTTP endpoint answers, not when its process exists — a process that is alive but no longer responding reports as degraded, which is the failure this is built to catch.

Memory.

npx fozikio memory health                  # memory health report
npx fozikio memory vitals                  # behavioral vitals and prediction error
npx fozikio memory wander --from "auth"    # seeded walk through the graph
npx fozikio memory maintain fix            # scan and repair data issues
npx fozikio memory report                  # weekly quality report
npx fozikio tools --category memory        # browse the cognitive tool catalogue
npx fozikio migrate --from sqlite:./cortex.db --to json:./backup.json --verify

The pre-memory spellings (fozikio health, fozikio vitals, …) still work and are not deprecated — existing scripts need no changes.

Every command takes --json for machine-readable output and honours NO_COLOR; styling and progress indicators switch off automatically when output is piped. --yes skips confirmations for unattended use. Read-only commands honour --namespace <ns> and --agent <name>; in a workspace with .fozikio/agent.yaml, the agent's default_namespace is picked up automatically — no flag needed.

Development

npm run dev       # tsc --watch
npm test          # vitest run
npm run test:watch

Environment Variables

Variable	Required	Description
CORTEX_API_TOKEN	Optional	Used by the cortex-telemetry hook to send retrieval feedback to the cortex API. Not required to run the MCP server.
MOONSHOT_API_KEY	Optional	Required when llm: kimi is set. Get one from platform.moonshot.cn.
OPENAI_API_KEY	Optional	Required when llm: openai is set, or when using any OpenAI-compatible provider without an explicit API key.

Additional variables are required depending on which providers you enable (Firestore, Vertex AI, etc.). See docs/ for provider-specific configuration.

Rules, Skills & Agents

fozikio init automatically installs safety rules, skills, and agent definitions from the fozikio.json manifest into the target workspace.

Safety Rules (Reflex)

cortex-engine ships with Reflex rules — portable YAML-based guardrails that work across any agent runtime, not just Claude Code.

Rule	Event	What It Does
cognitive-grounding	prompt_submit	Nudges the agent to call query() before evaluation, design, review, or creation work
observe-first	file_write / file_edit	Warns if writing to memory directories without calling observe() or query() first
note-about-doing	prompt_submit	Suggests capturing new threads of thought with thread_create()

Rules live in reflex-rules/ as standard Reflex YAML. They're portable — use them with Claude Code, Cursor, Codex, or any runtime with a Reflex adapter. See @fozikio/reflex for the full rule format and tier enforcement.

Claude Code users also get platform-specific hooks (in hooks/) for telemetry, session lifecycle, and project board gating. These are runtime adapters, not rules — they handle side effects that the declarative rule format doesn't cover.

To customize: Edit the YAML rule files directly, or set allow_disable: true and disable them via Reflex config.

Skills

Skills are invocable workflows that agents can use via /skill-name.

Skill	When to Use	What It Provides
cortex-memory	Query, record, and review work	Full memory workflow — query/observe patterns, belief tracking, memory-grounded code review, session patterns

Agents

Agent	Description
cortex-researcher	Deep research agent that queries cortex before external sources, observes novel findings back into memory

How Auto-Install Works

• fozikio init reads fozikio.json from the package root
• Copies hooks, skills, and Reflex rules into the target workspace
• Missing source files are skipped with a warning — init never fails due to missing assets

Built-in Capabilities (v1.0.0+)

As of v1.0.0, all 60 cognitive tools are built into cortex-engine core — no separate plugin installs needed. Previously these were separate @fozikio/tools-* packages; they've been absorbed into the engine.

Capability	Tools
Memory	observe, query, recall, wander, wonder, forget, retrieve, context, feedback, query_cross, federated_query
Beliefs & Reasoning	believe, belief, contradict, speculate, validate, predict
Threads	thread_create, thread_update, thread_resolve, threads_list
Journaling	journal_write, journal_read
Identity	evolve, evolution_list
Social	social_read, social_update, social_draft, social_score
Graph	neighbors, suggest_links, suggest_tags, link, graph_report
Maintenance	dream, digest, reflect, abstract, find_duplicates, retrieval_audit, consolidation_status
Vitals	vitals_get, vitals_set, sleep_pressure
Reasoning	surface, ruminate, notice, intention, resolve
Content	content_create, content_list, content_update
Ops	ops_append, ops_query, ops_update
Goals	goal_set
Agents	agent_invoke
Stats	stats, query_explain

The plugin system is still available for custom extensions — see Plugin Docs.

Documentation

• In-repo docs:
  • Quick Start — 5-minute setup
  • Storage backends — SQLite vs Firestore vs JSON, migration paths
  • Concurrency model — withTransaction contract, single-process invariant, SQLite vs Firestore semantics
  • Tools reference — all 60 tools by category with when-to-use guidance (auto-generated)
  • Multi-agent design — namespace isolation, bridges, federation
  • Design specs — design documents from the v1.2.0 audit-driven refactor
  • Agent-first setup — Workspace initialization walkthrough
• Discussions — Ask questions, share what you've built
• Contributing — How to contribute
• Project Board — Roadmap and active work
• Security — Report vulnerabilities

Community

• r/Fozikio — Project subreddit
• GitHub Discussions — Questions, feedback, show what you've built
• "I built 44 MCP tools for my cognitive system" — r/mcp deep dive (84 upvotes, 27 comments)
• "Gave my agent a subconscious" — r/clawdbot walkthrough (22 upvotes, 34 comments)

Related Projects

• @fozikio/reflex — Portable safety guardrails for agents. Rules as data, not code.
• sigil — Agent control surface. Signals and gestures, not conversations.
• fozikio.com — Documentation and guides

License

MIT — see LICENSE