# Cortex

> Organizational memory for AI agents captures decisions into a knowledge graph and serves them over MCP.

- **Type:** MCP server
- **Install:** `agentstack add mcp-askmy-stack-cortex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [askmy-stack](https://agentstack.voostack.com/s/askmy-stack)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [askmy-stack](https://github.com/askmy-stack)
- **Source:** https://github.com/askmy-stack/cortex
- **Website:** https://cortex-blush-theta.vercel.app

## Install

```sh
agentstack add mcp-askmy-stack-cortex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Cortex

[](https://github.com/askmy-stack/cortex/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
[](mcp/)

**The organizational memory operating system for AI-native companies.**

> Give every AI agent in your organization the same context a senior engineer has and keep it current as your organization evolves.

**Thesis:** AI tools are stateless. Organizations are not. Every agent starting from zero is a **memory infrastructure failure** not a model failure.

  

  Capture decisions from every tool → structure in a knowledge graph → actively inject context at inference time via MCP.

| In 3 minutes | Command |
|---|---|
| **Live demo** | [cortex-blush-theta.vercel.app](https://cortex-blush-theta.vercel.app) (dashboard; set `CORTEX_API_ORIGIN` on Vercel for API-backed search) |
| **Run locally** | `make demo` → [localhost:3000](http://localhost:3000) |
| **Ask a question** | Workspace `local-dev` → *Why CockroachDB for payments?* |
| **Wire an agent** | Add the MCP block below — `cortex_query`, `cortex_inject`, `cortex_remember` |

---

## The Problem

Every company running AI today has the same silent failure.

Tools think. Agents act. Nothing remembers.

- A Cursor session doesn't know what was decided in the Slack thread
- The support agent doesn't know the sales context from last quarter
- The new engineer's Copilot doesn't know why the architecture was built this way
- The code review bot doesn't know which constraints are architectural vs. temporary

Every AI interaction starts from zero. Every time.

This isn't a model problem. Every major lab has solved reasoning.

**It's a memory infrastructure problem.** And no tool has solved it.

---

## What Cortex Does

```
Captures decisions → Structures them → Injects context → Agents act intelligently
```

**Cortex captures decisions, not documents.**

When your team decides to migrate the payments service to CockroachDB, Cortex captures:

```json
{
  "type": "architectural_decision",
  "decision": "Migrate payments service to CockroachDB",
  "replaces": "PostgreSQL",
  "rationale": ["scale ceiling at 10M txn/day", "multi-region replication needed"],
  "made_by": ["priya@", "dan@"],
  "triggered_by": "incident #247",
  "affects": ["payments-service", "billing-service"],
  "date": "2026-05-09",
  "status": "active"
}
```

Not the Slack message. Not a document. The **decision** — structured, linked, queryable.

**Then Cortex actively injects it.**

When any agent touches the payments service, Cortex enriches its context automatically:

```
"Why does payments use CockroachDB?"
→ Cortex returns: the incident that triggered it, who decided it,
  the tradeoffs discussed, the migration PR, known edge cases since.
→ Agent answers correctly. No hallucination. No archaeology.
```

---

## Key Capabilities

| Capability | Description |
|---|---|
| **Decision capture** | Extracts structured decisions from Slack, GitHub, Jira, Linear, meetings |
| **Knowledge graph** | Neo4j graph: Decision → Person → System → Exception → Outcome |
| **Active injection** | Pushes relevant context to agents before they act — not after they ask |
| **MCP server** | Native MCP endpoint — any Claude, Cursor, or MCP agent gets memory in one config line |
| **Importance scoring** | Filters noise at ingestion — only signal reaches the graph |
| **Trust scoring** | Bayesian confidence per memory node — bad inputs don't corrupt memory |
| **Contradiction detection** | Flags when new events conflict with existing memory — no silent overwrites |
| **Memory decay** | Old memory compresses and archives on a principled schedule |
| **Coverage scoring** | Per-domain completeness estimate — agents know when memory is thin |
| **RBAC** | Graph-level access control — contractors don't see salary decisions |
| **Outcome tracking** | Links decisions to real metrics — memory becomes self-correcting |
| **GDPR erasure** | Cascade delete with audit trail; query cache invalidated per workspace |

---

## Production hardening (launch-ready)

These behaviors matter when Cortex runs behind auth in preview or production:

| Concern | Behavior |
|---|---|
| **GDPR erasure** | `POST /gdpr/erase` bumps a per-workspace Redis cache epoch — stale PII cannot be served from `/query` for up to 60s |
| **Dashboard proxy** | nginx on `:3000` forwards `/gdpr` (and `/query`, `/inject`, …) to the API — same-origin demos work |
| **Demo smoke test** | `scripts/demo.sh` sources `.env` and sends `Authorization` when `CORTEX_DEMO_API_KEY` or `CORTEX_API_KEYS` is set |
| **Pipeline retries** | Transient Neo4j errors do not commit Kafka offsets or land in DLQ — messages are redelivered |
| **CMVK fail-fast** | `CORTEX_CMVK_BACKEND=openai\|ollama` validates credentials/reachability at worker startup |

```bash
# Preview / staging .env snippet
CORTEX_API_KEYS=preview-key:admin;authenticated
CORTEX_DEMO_API_KEY=preview-key
CORTEX_CMVK_BACKEND=heuristic   # zero-cost local demo; use openai + OPENAI_API_KEY in prod
```

Regenerate the README animation: `python scripts/generate_readme_demo_gif.py` → `docs/assets/cortex-memory-fabric.gif`

---

## Deploy

| Goal | Guide |
|------|--------|
| **$0 portfolio demo** (Cloudflare Pages + Render free + Aura + Upstash) | [docs/DEPLOY-FREE.md](docs/DEPLOY-FREE.md) |
| **Production split** (Vercel dashboard + Railway/Render API) | [docs/DEPLOY.md](docs/DEPLOY.md) |

After deploy, verify end-to-end: `./scripts/verify_free_deploy.sh --api https://YOUR_API --pages https://YOUR_PAGES`

---

## Architecture

```
┌──────────────────────────────────────────────────────────────┐
│  CAPTURE LAYER                                                │
│  Slack · GitHub · Jira · Linear · Meetings · CI/CD          │
│  Real-time event streams via webhooks + OAuth connectors     │
└───────────────────────────────┬──────────────────────────────┘
                                │ Kafka
┌───────────────────────────────▼──────────────────────────────┐
│  EXTRACTION ENGINE                                            │
│  Decision extractor (GPT-4o structured output)              │
│  Entity resolver (spaCy NER → canonical org entities)       │
│  Importance scorer (filters noise before storage)           │
│  Event classifier (decision/exception/rationale/update)     │
└───────────────────────────────┬──────────────────────────────┘
                                │
┌───────────────────────────────▼──────────────────────────────┐
│  MEMORY FABRIC                                                │
│  Episodic    → TimescaleDB  what happened and when           │
│  Semantic    → Qdrant       what things mean                 │
│  Structural  → Neo4j        relationships + causal chains    │
│  Procedural  → Neo4j        how things are done              │
│  Hot cache   → Redis         *"Why does the payments service use CockroachDB instead of Postgres?"*

| Without Cortex | With Cortex |
|---|---|
| Agent guesses or says *"I don't know"* | Returns incident #247, decision owners, tradeoffs, migration PR, edge cases since |
| Slack archaeology, stale Confluence | Structured `DecisionEvent` from the live graph |
| Every session starts at zero | MCP `cortex_inject` pushes context **before** inference |

Full context. ~3 seconds. No archaeology.

```mermaid
sequenceDiagram
    participant Agent as Cursor / Claude
    participant MCP as Cortex MCP
    participant API as Context API
    participant Graph as Neo4j + Redis

    Agent->>MCP: cortex_query("CockroachDB payments")
    MCP->>API: POST /query
    API->>Graph: RBAC-filtered search + cache
    Graph-->>API: decisions + lineage
    API-->>MCP: ranked memory
    MCP-->>Agent: incident, owners, rationale, systems
```

---

## Project Structure

```
cortex/
├── connectors/           # Tool connectors (Slack, GitHub, Jira, Linear)
│   ├── slack/
│   ├── github/
│   ├── jira/
│   └── linear/
├── extraction/           # Decision extractor, entity resolver, classifier
├── scoring/              # Importance scorer, trust scorer, coverage scorer
├── graph/                # Neo4j schema, migrations, Cypher queries
│   └── migrations/       # V001__initial_schema.cypher, etc.
├── pipeline/             # Kafka extraction worker (raw → graph)
├── memory/               # Episodic (Timescale) + semantic (Qdrant) helpers
├── intelligence/         # Contradiction detector, decay engine, outcome linker
├── api/                  # FastAPI application
├── mcp/                  # MCP server (TypeScript)
├── sdk/                  # Python client (query, inject, remember)
├── frontend/             # React dashboard
├── infrastructure/       # Terraform, Docker configs
├── tests/
├── scripts/              # Setup, seed data, utilities
├── docs/                 # Architecture diagrams, ADRs
├── CLAUDE.md             # Agent operating instructions
├── SESSIONS.md           # Build session log
├── DECISIONS.md          # Decision log + agent instructions
├── MISTAKES.md           # Errors and learnings
└── ARCHITECTURE.md       # Full system architecture spec
```

---

## Tech Stack

| Layer | Technology |
|---|---|
| Event streaming | Apache Kafka |
| Decision extraction | GPT-4o function calling (prod) / Ollama Gemma (dev) |
| NER + entity resolution | spaCy + custom models |
| Knowledge graph | Neo4j 5 |
| Vector store | Qdrant |
| Time-series | TimescaleDB |
| Cache | Redis |
| API | FastAPI + JWT |
| MCP server | TypeScript (MCP SDK) |
| Agent runtime | LangGraph |
| Frontend | React + Vite (dashboard: Ask, memory map, Cortex Guide) |
| IaC | Terraform + AWS ECS |
| Observability | Prometheus + Grafana |
| ML tracking | MLflow |
| Auth | Auth0 + JWT + DID (agent identity) |

---

## Roadmap

| Phase | Scope | Status |
|---|---|---|
| Phase 0 | Architecture + documentation | ✅ Done |
| Phase 1 | Kafka + Slack connector + decision extractor | ✅ Core shipped |
| Phase 2 | GitHub + Jira + Linear connectors + Neo4j graph | ✅ Shipped (webhooks → Kafka → worker) |
| Phase 3 | REST API (`/query`, `/inject`) + MCP + Python SDK | ✅ Shipped |
| Phase 4 | Importance + trust scoring + graph RBAC | ✅ Shipped |
| Phase 5 | Contradiction detector + decay engine | ✅ Shipped |
| Phase 6 | React dashboard (Ask, memory map, guide, agent inject) | ✅ Shipped |
| Phase 7 | Live demo URL + demo video + open-source launch | 🔄 In progress |
| Phase 8 | Outcome tracking + coverage scoring | ⏳ Post-launch |
| Phase 9 | Elicitation bot (implicit knowledge) | ⏳ Post-launch |
| Phase 10 | Federated cross-org memory | ⏳ v2 |

**CI:** GitHub Actions runs `pytest` + seed dry-run on push/PR ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)).

---

## Why This Exists

Every existing solution falls into one of two camps:

**Memory systems** (Mem0, Zep, Cognee) — deep on architecture, no cross-tool capture, single-agent scope, no decision extraction.

**Enterprise search** (Glean, Notion AI, Dust) — deep on connectors, pull-based only, no temporal graph, no causal reasoning, no decision capture.

Cortex is the infrastructure layer in the gap between both camps.

The combination — cross-tool capture + decision extraction + temporal causal graph + active MCP injection + importance scoring + organizational scope — does not exist in any open-source or commercial product.

---

## Research Foundation

Built on:
- **MAGMA** (arXiv:2601.03236) — four-graph memory architecture (semantic/temporal/causal/entity)
- **Zep/Graphiti** (arXiv:2501.13956) — temporal edge invalidation, 90% latency reduction
- **A-MEM** (NeurIPS 2025, arXiv:2502.12110) — Zettelkasten dynamic memory linking
- **Field-Theoretic Memory** (arXiv:2602.21220) — thermodynamic memory decay (+116% F1)
- **SSGM Framework** (arXiv:2603.11768) — memory stability and safety governance
- **Context Engineering** (arXiv:2603.09619) — CE as organizational infrastructure

---

## License

Apache 2.0 — use it, fork it, build on it.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [askmy-stack](https://github.com/askmy-stack)
- **Source:** [askmy-stack/cortex](https://github.com/askmy-stack/cortex)
- **License:** Apache-2.0
- **Homepage:** https://cortex-blush-theta.vercel.app

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-askmy-stack-cortex
- Seller: https://agentstack.voostack.com/s/askmy-stack
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.