Memnex

Cross-channel permanent memory for AI agents.

Memnex is a memory service for conversational AI agents. When the same user moves from a phone call to WhatsApp to web chat, every agent on every channel already knows what happened on the previous channels: same name, same open issues, same preferences, same history. No more "how can I help you today?" on channel three.

It plugs in over the Model Context Protocol (MCP), so any MCP-compatible agent (Claude Desktop, Cursor, LangGraph, CrewAI, your own runtime) can use it without writing integration code.

Why this exists

Most agent platforms have short-term conversation memory (the chat scrollback). They don't have long-term, cross-channel memory. So a customer who calls support on Monday and messages on Wednesday talks to two strangers, even when both are powered by the same LLM. They re-explain everything. Trust evaporates.

Memnex fixes this by being a shared memory layer the agents talk to. Each agent writes durable facts as the conversation unfolds (intent, preferences, issues, resolutions, profile attributes), and reads them back at the start of every turn. When channels hand off, nothing is lost. When a session disconnects mid-flow, only the un-written facts are lost. Write per sub-intent and even that goes away.

Quick start

As an MCP server (recommended for agent runtimes)

Memnex is open-source and self-hosted. Run the server yourself (your machine, your cloud, Railway, Fly.io, AWS, GCP, anywhere a Python process can run); your agents connect to it over MCP.

pip install memnex
export GOOGLE_API_KEY=...                  # for embeddings
export MEMNEX_POSTGRES_URL=postgres://...  # or leave unset for in-memory (dev only)
export MEMNEX_DEV_KEY=1                    # auto-creates a dev API key on boot
memnex serve mcp --transport stdio
# stderr: [memnex] MEMNEX_SECRET_KEY=mx_live_k.....

Take the printed key and put it in your MCP client config:

{
  "mcpServers": {
    "memnex": {
      "command": "memnex",
      "args": ["serve", "mcp", "--transport", "stdio"],
      "env": {
        "MEMNEX_SECRET_KEY": "mx_live_kXXXXXXXX_<secret>",
        "MEMNEX_CHANNEL": "voice"
      }
    }
  }
}

For a real network endpoint instead of a stdio subprocess, run memnex serve mcp --transport streamable-http --port 8500 and point your client at http://your-host:8500/mcp with the same API key in headers.

Common deployment mistake: putting GOOGLE_API_KEY or MEMNEX_POSTGRES_URL in the client env block. Those are server-side infrastructure secrets. Set them where the server runs, never in the agent's MCP config. The client only ever needs MEMNEX_SECRET_KEY and MEMNEX_CHANNEL. See Configuration for the full split.

Tenants integrate via MCP, not by importing Memnex into Python. The Python codebase is what runs on the server. Self-hosters and contributors may run it directly. See the operator guide for that path.

What the MCP server exposes

Three primitives: Tools (functions the agent calls), Resources (read-only data the host app fetches), Prompts (reusable templates the host can pull).

Tools (5)

Example call:

{
  "tool": "memory_write",
  "arguments": {
    "user_id": "u_123",
    "facts": [
      {
        "fact": "Wants to cancel order XYZ",
        "type": "intent",
        "entities": ["order:XYZ"],
        "confidence": 0.95
      }
    ]
  }
}

Resources (3)

Prompts (3)

Architecture

                   ┌────────────────┐
   Voice agent ──▶ │                │
                   │                │      Identity ──▶ phone / wa / email / web normalization
WhatsApp agent ──▶ │  MCP / REST /  │ ──▶  Memory   ──▶ extract · score · conflict · compress
                   │   stdio        │      Privacy  ──▶ regex + Presidio · GDPR forget
   Web agent  ──▶  │                │      Audit    ──▶ HMAC-signed write ledger
                   └────────────────┘
                          │
                          ▼
              ┌─────────┬─────────┬─────────┐
              │  Redis  │ Postgres│ Qdrant  │
              │  (hot)  │ (warm,  │(semantic│
              │         │  RLS)   │  vector)│
              └─────────┴─────────┴─────────┘
                          ▲
                          │
                      embeddings

All four layers (Identity, Memory, Privacy, Audit) are tenant-scoped. Storage is pluggable behind HotStore / WarmStore / SemanticStore protocols, so the same code runs against in-memory backends in tests and real services in production.

See the architecture doc for the full design.

Configuration

Two distinct sets of environment variables. Mixing them up is the single most common deployment mistake.

Server-side (set by whoever runs the Memnex server)

These are infrastructure secrets. They live on the operator's side. Never copy these into an MCP client config.

Generative LLM (legacy, opt-in): MEMNEX_LLM_PROVIDER and MEMNEX_LLM_API_KEY only have an effect if you explicitly switch the provider away from the default none. They are used solely by the legacy raw_text extraction path; the structured-fact path that all current tools and prompts recommend never invokes a generative LLM. Most operators can leave both unset.

Client-side (set by the tenant in their MCP client config)

A copy-paste-ready template is at .env.example.

Storage backends

All four are gated behind protocol interfaces in src/memnex/storage/base.py. A new backend is one new class implementing the protocol; no core changes required.

How we compare

Quick orientation. None of these are exact substitutes for each other; pick based on what matters most to you.

If you want a hosted memory backend bolted to ChatGPT, use OpenAI memory. If you want the smallest possible API for a single-app agent, use Mem0. If you need cross-channel, multi-tenant, compliance-aware memory exposed over MCP, that's where Memnex sits.

See the comparison doc for the longer version.

Documentation

Full documentation lives in the docs/ directory on GitHub. Routed by audience:

• Integrating an AI agent with Memnex: integration guide
• Running Memnex yourself: operator guide
• Reference: MCP API, REST + Python API, architecture, security
• Status and direction: features, comparison, roadmap

Contributing

PRs welcome. Read CONTRIBUTING.md for the dev loop and the architectural invariants we hold to. For security issues, see SECURITY.md.

License

Apache License 2.0. See LICENSE.