cortex-memory

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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](https://github.com/Fozikio/cortex-engine) (MIT) | [npm](https://www.npmjs.com/package/@fozikio/cortex-engine)

## Prerequisites

This skill requires [cortex-engine](https://github.com/Fozikio/cortex-engine) running as an MCP server. Install it separately before using this skill:

```bash
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:

```bash
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:

| Command | What it does |
|---|---|
| `fozikio up` | start every service and wait until it actually answers |
| `fozikio status` | service health (HTTP probe, not PID liveness); exits 1 if unhealthy |
| `fozikio doctor` | diagnose the install and say how to fix what is broken |
| `fozikio dashboard` | live service and memory view |
| `fozikio down` | stop services it started |

`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:**

```markdown
## 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

From Fozikio/cortex-engine, MIT.

More from Fozikio/cortex-engine