The knowledge + learning layer of the qlawbox research stack · View lab →
qortex
A knowledge layer for AI agents that improves with every correction
Vector search returns what's similar. qortex learns what's useful, and lets you watch it happen.
Screenshots
Grafana: Beta posteriors separate over a 2-hour window as the bandit learns which context actually helps
Results
5
Published packages
Core graph DB, ingestion, learning, and observability ship independently. Install what you need, nothing else.
Learns
Retrieval that improves
Accept and reject signals retrain the ranker through a Thompson-Sampling bandit, so good results rise and bad ones fade instead of sitting frozen in a vector store.
Portable
Laptop to production
One protocol fronts every backend: SQLite while you build, Postgres + pgvector or Memgraph in production. The same retrieval code runs at either scale.
AI assistants forget things between turns, and everything between conversations.
The usual fix is a vector store: embed the text, cosine-match the query, return the nearest neighbors. But this has two problems:
- It never learns, so a result that helped last week ranks no higher today.
- It stays opaque: when it returns the wrong thing, nothing tells you why.
qortex is a protocol-driven knowledge and learning layer that addresses both.
The Sketch
Retrieval combines vector similarity with Personalized PageRank over a typed-edge knowledge graph, so structurally related concepts surface even when cosine similarity misses them. A Thompson-Sampling bandit sits on top. Accepted results boost the arms that produced them, rejected ones get suppressed, and reward credit propagates backward across the graph's typed edges. Feedback makes retrieval better instead of leaving it frozen.
Run Everywhere
One command installs it as an MCP server (claude mcp add qortex -- uvx qortex mcp-serve). A Starlette REST API exposes the same surface to anything that speaks HTTP. Backends swap behind one protocol: SQLite on a laptop, Postgres with pgvector or Memgraph in production. The same code runs at either scale.
The Ecosystem
qortex is a five-package monorepo built on PEP 420 namespace packaging: qortex (core retrieval and service), qortex-ingest (pluggable document ingestors), qortex-online (real-time concept extraction and graph wiring), qortex-learning (the Thompson-Sampling bandit and reward models), and qortex-observe (the instrumentation spine). Each publishes independently to PyPI, yet imports as one qortex.* tree.
The screenshots above are live dashboards, captured from a running instance. As the bandit gathers feedback, the arms that keep producing useful results pull ahead of the ones that do not, and you can watch that separation happen in real time. Newly extracted knowledge starts in a buffer and only graduates into the persistent graph once the system is confident enough in it. A single query traces end to end, from the inbound MCP message through graph traversal and vector retrieval down to the decision about what to return. You can watch the agent learn, and catch it when it learns the wrong thing.
For Engineers
Architecture
Tracing a Round-Trip
A query runs vector similarity first, then expands through the graph via Personalized PageRank when the backend supports MAGE, and falls back to a depth-decayed BFS when it does not. Activated concepts group by domain and their rules get collected. Feedback flows back through the learning layer, which updates Beta posteriors per arm and propagates credit backward through ancestor concepts, decayed by hop distance and edge strength.
Running alongside all of it, qortex-observe taps every phase with an @traced decorator. OpenTelemetry spans export over OTLP (viewed in Jaeger or Tempo), Prometheus metrics feed Grafana, and structured events also land in JSONL sinks for offline replay. The metrics are the ones a learning system actually needs: posterior means, selection and observation rates, credit-propagation depth, PPR iterations to convergence, latency by phase.
The service, MCP, REST, and learning layers are async; the graph backends still wrap the synchronous neo4j driver. That migration is in progress.
Key Decisions
Retrieval as a learning problem
Most memory layers are write-once vector stores. qortex models the question of what to retrieve as a contextual bandit and updates Beta posteriors from accept/reject feedback via Thompson Sampling.
Instrument first, demo second
qortex-observe is a first-class package. Every selection, observation, and posterior update emits a structured event, so the learning dynamics show up in Grafana in real time. This facilitates catching reward misspecification before it compounds, then correcting it with a tunable reward signal.
Prove integrations, then consolidate into a platform
I built native adapters across the major agent frameworks (LangChain, Mastra, agno, AutoGen, CrewAI), including standalone published packages like langchain-qortex on PyPI and @peleke.s/mastra-qortex on npm.Then I consolidated the surface behind a service model. MCP plus a REST API lets any language or runtime consume the full stack over HTTP, instead of maintaining a dozen brittle per-framework integrations forever.
One backend protocol, many deployments
A single GraphBackend protocol fronts an in-memory backend for tests; SQLite for local use; and Memgraph (with MAGE for real Personalized PageRank) in production. The vector index swaps the same way between sqlite-vec and pgvector. Capability is detected at runtime, so retrieval checks for MAGE and falls back to BFS rather than failing.
Stack