cortex-memory

Cortex Memory

Persistent memory engine for AI agents. Knowledge survives across sessions — recall what you learned last week, track evolving beliefs, detect contradictions, and build a knowledge graph over time.

Source: github.com/Fozikio/cortex-engine (MIT) | npm

Prerequisites

This skill requires cortex-engine running as an MCP server. Install it separately before using this skill:

npm install -g @fozikio/cortex-engine

Install the scoped package, unpinned. The unscoped cortex-engine on npm is the old name and is deprecated — but old versions of it still resolve, so pinning one installs an ancient engine that works just well enough to hide the problem. Always use @fozikio/cortex-engine, and let it take the latest.

Then initialize and start:

fozikio init my-agent    # scaffold a workspace
fozikio up               # start ollama + nli, wait until they answer
fozikio serve            # start the MCP server (stdio)

If anything goes wrong, fozikio doctor diagnoses the install and tells you how to fix it.

Runs locally with SQLite + Ollama. No cloud accounts needed. The skill instructions below are read-only — they teach your agent how to use cortex tools, they don't execute anything.

Managing the services

cortex-engine 1.4.0+ ships a service supervisor, so you do not have to babysit Ollama:

status and up use an HTTP probe rather than checking whether a process exists, because a wedged process still holds the port. They also adopt rather than kill: if fozikio did not start a process, it will not stop it — which matters when the Ollama desktop app or another agent already owns :11434.

Core Loop

Read before you write. Always check what you already know before adding more.

Search

query("authentication architecture decisions")

Be specific. query("JWT token expiry policy") beats query("auth"). Results include relevance scores and connected concepts.

Explore around a result:

neighbors(memory_id)

Record

Facts — things you confirmed:

observe("The API rate limits at 1000 req/min per API key, not per user")

Questions — unresolved:

wonder("Why does the sync daemon stall after 300k seconds?")

Hypotheses — unconfirmed ideas:

speculate("Connection pooling might fix the timeout issues")

Update beliefs

believe(concept_id, "Revised understanding based on new evidence", "reason")

Track work across sessions

ops_append("Finished auth refactor, tests passing", project="api-v2")
ops_query(project="api-v2")  # pick up where you left off

Memory-Grounded Reviews

Review code or designs by comparing against accumulated knowledge:

1. Ground: query("the domain being reviewed") — load past decisions and patterns
2. Compare: Does the work align with or diverge from established patterns?
3. Record: observe() new patterns, wonder() about unclear choices, believe() updated understanding
4. Output:

## Review — Grounded in Memory

### Aligned with known patterns
- [matches cortex context]

### Divergences
- [what differs, intentional or accidental]

### New patterns to capture
- [novel approaches worth observing]

Session Pattern

1. Start: query() the topic you're working on
2. During: observe() facts, wonder() questions as they come up
3. End: ops_append() what you did and what's unfinished
4. Periodically: dream() to consolidate memories (compress, abstract, prune)

Available Tools

60 tools across 13 categories. Run fozikio tools for the full list with descriptions.

Beyond the basics

• threads — multi-session explorations. A thread is something you want to keep thinking about, distinct from an ops log entry recording what happened.
• journal / evolution — identity change over time. evolve() proposes a shift; evolution_resolve() applies, rejects, or reverts it, so the ledger reflects what was actually adopted rather than only what was suggested.
• beliefs — contradict() adjudicates whether an observation genuinely conflicts with an existing memory (via NLI, falling back to the LLM) and records a CONTRADICTION or TENSION signal rather than silently overwriting.
• meta — sleep_pressure() and consolidation_status() tell you whether dream() is overdue; retrieval_audit() and query_explain() show why a query returned what it did.