@peleke.s/mastra-qortex

MastraVector backed by qortex — graph-enhanced retrieval via MCP.

A MastraVector implementation that gives any Mastra app access to qortex's knowledge graph. Works alongside Mastra's existing 22+ vector stores, adding:

• Graph navigation — typed edges, neighbors, and rules from any search result
• Feedback-driven learning — accepted results rank higher next time (PPR teleportation)
• Rules auto-surfaced — domain constraints and patterns linked to concepts

Install

npm install @peleke.s/mastra-qortex

Requires a running qortex MCP server (pip install qortex).

Quick start

import { QortexVector } from "@peleke.s/mastra-qortex";

const qortex = new QortexVector({
  id: "qortex",
  serverCommand: "uvx",
  serverArgs: ["qortex", "mcp-serve"],
});

// Standard MastraVector API — works everywhere Mastra expects a vector store
await qortex.createIndex({ indexName: "docs", dimension: 384 });
await qortex.upsert({
  indexName: "docs",
  vectors: embeddings,
  metadata: chunks.map((c) => ({ text: c.text, source: c.source })),
});

const results = await qortex.query({
  indexName: "docs",
  queryVector: queryEmbedding,
  topK: 10,
});

What qortex adds

Graph exploration

// Text-level query (uses qortex's embedding + optional PPR)
const queryResult = await qortex.textQuery("authentication protocols", {
  domains: ["security"],
  mode: "graph", // PPR-enhanced retrieval
});

// Navigate the knowledge graph from any result
const explored = await qortex.explore(queryResult.items[0].node_id);
console.log(explored.edges);     // Typed relationships
console.log(explored.neighbors); // Connected concepts
console.log(explored.rules);     // Linked rules

Feedback loop

// Tell qortex what worked
await qortex.feedback(queryResult.query_id, {
  [queryResult.items[0].id]: "accepted",
  [queryResult.items[4].id]: "rejected",
});

// Future queries benefit from this signal

Rules

const rules = await qortex.getRules({
  domains: ["security"],
  categories: ["architectural"],
});

for (const rule of rules.rules) {
  console.log(`[${rule.category}] ${rule.text}`);
}

Architecture

Mastra App (TypeScript)
  └── QortexVector extends MastraVector
       └── QortexMcpClient (stdio JSON-RPC)
            └── qortex MCP server (Python subprocess)
                 ├── VectorIndex (cosine similarity)
                 └── GraphBackend (PPR, rules, typed edges)

QortexVector talks to the qortex MCP server over stdio. The server manages vector indexes, the knowledge graph, and the feedback loop. All 9 MastraVector methods map to qortex_vector_* MCP tools.

Documentation

• MastraVector Integration Guide — full API reference
• Case Study — why we built this, what we proved
• qortex documentation — core library

License

MIT