How MemNexus Works

Architecture Overview

MemNexus is built as a set of services that work together:

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│   mx CLI    │  │  TypeScript  │  │  MCP Server  │
│             │  │     SDK      │  │  (Claude,    │
│             │  │              │  │   Cursor)    │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │
       └────────────────┼────────────────┘
                        │
                        ▼
               ┌────────────────┐
               │  API Gateway   │
               │  (Kong)        │
               │  Auth + Rate   │
               │  Limiting      │
               └───────┬────────┘
                       │
                       ▼
               ┌────────────────┐
               │  Core API      │
               │  (Node.js /    │
               │   Express)     │
               │  40+ endpoints │
               └───────┬────────┘
                       │
                       ▼
               ┌────────────────┐
               │  Neo4j         │
               │  Graph DB      │
               │  + Vector      │
               │    Indexes     │
               └────────────────┘

Components

Core API

The central service handling all data operations. Built with Node.js and Express, it provides 40+ REST endpoints organized into route groups:

• Memories — CRUD operations, search, temporal queries
• Conversations — Session management, timeline reconstruction
• Facts — Knowledge graph operations (subject-predicate-object)
• Topics — Clustering and co-occurrence analysis
• Communities — Graph community detection (Louvain, label propagation)
• Patterns — Behavioral pattern detection
• GraphRAG — Advanced graph-based retrieval
• Entities — Entity extraction and discovery

API Gateway

A Kong-based gateway that handles authentication (API keys), rate limiting, and request routing. All client traffic flows through the gateway before reaching the Core API.

Neo4j Graph Database

MemNexus stores everything in a Neo4j graph database. This is a deliberate architectural choice — graph databases excel at representing relationships between memories, topics, entities, and facts.

Neo4j also provides:

• Vector indexes for semantic search using OpenAI embeddings
• Full-text indexes for keyword search
• Graph traversal for relationship-based queries

Search Pipeline

When you search for memories, MemNexus runs a hybrid search:

1. Semantic search — Your query is embedded using OpenAI's embedding model, then compared against memory embeddings using cosine similarity
2. Keyword search — Full-text search across memory content using Neo4j's built-in text indexes
3. Reciprocal Rank Fusion (RRF) — Results from both searches are merged and ranked using RRF to produce the final result set

This hybrid approach means you can search by meaning ("that deployment issue") or by exact terms ("ECONNREFUSED error") and get relevant results either way.

Authentication

MemNexus uses API keys for authentication. Keys follow the format:

cmk_live_<id>.<secret>

You pass your API key as a Bearer token in the Authorization header, or configure it once in the CLI.

Data Flow

Here is what happens when you create a memory:

1. You call mx memories create (or the SDK/API equivalent)
2. The request hits the API Gateway, which validates your API key
3. The Core API receives the request and:
   • Generates an OpenAI embedding for the content
   • Extracts topics and entities
   • Detects the conversation boundary (or uses the one you specified)
   • Stores the memory node and all relationships in Neo4j
4. The memory is immediately searchable

Next Steps

• Quick Start — Try it yourself
• CLI Installation — Set up the mx CLI
• SDK Installation — Integrate via TypeScript SDK