Nexus Memory

Zero-dependency, file-based persistent memory for AI agents.

Glama Smithery License: MIT

Nexus is a tiered memory system with Ebbinghaus decay, keyword retrieval, token-efficient context assembly, and full MCP + REST API support. Drop-in replacement for Hindsight that saves 92% on memory token costs.

MCP Server  →  stdio (Claude Code, Cline, Windsurf)
REST API    →  HTTP (Hermes agents, custom integrations)
CLI         →  bash (nexus.sh — search, stats, decay, consolidate)

Features

Quick Start

# 1. Start the MCP server (for Claude Code / Cline / Windsurf)
python nexus_mcp.py

# 2. Start the REST API (for Hermes agents / HTTP clients)
python nexus_rest.py --port 9177

# 3. Use the CLI
python nexus_engine.py retrieve "what do I know about X"
python nexus_engine.py stats
python nexus_engine.py decay

Claude Code Integration

Add to your claude.json:

{
  "mcpServers": {
    "nexus-memory": {
      "command": "python",
      "args": ["path/to/nexus_mcp.py"]
    }
  }
}

Hermes Agent Integration

Replace Hindsight with Nexus:

export HINDSIGHT_API_URL=http://localhost:9177

No code changes needed. Nexus speaks the Hindsight v1 protocol.

Architecture

┌─────────────────────────────────────────────────────┐
│                    Nexus System                      │
│                                                      │
│  ┌──────────────┐  ┌──────────┐  ┌───────────────┐  │
│  │  nexus_mcp.py │  │nexus_rest│  │nexus_engine.py│  │
│  │  (MCP stdio)  │  │(HTTP API)│  │  (Core logic) │  │
│  └──────┬───────┘  └────┬─────┘  └───────┬───────┘  │
│         └───────────────┼─────────────────┘          │
│                         ▼                           │
│              ┌──────────────────┐                    │
│              │  memory/  (files) │                    │
│              │  ├ episodic/     │                    │
│              │  ├ semantic/     │                    │
│              │  ├ procedural/   │                    │
│              │  ├ reflections/  │                    │
│              │  ├ working/      │                    │
│              │  ├ core/         │                    │
│              │  └ archive/      │                    │
│              └──────────────────┘                    │
└─────────────────────────────────────────────────────┘

Memory Tiers

Token Economics

Benchmark: 1192.9x efficiency ratio (1 token spent → 1192 saved vs Hindsight).

Pricing

           Free              Solo              Team              Enterprise
           ─────            ──────            ──────            ──────────
Price      $0               $4.99/mo          $14.99/mo         $49.99/mo
Memories   50               500               5,000             50,000
MCP        ✓                ✓                 ✓                 ✓
REST API   ✓                ✓                 ✓                 ✓
CLI        ✓                ✓                 ✓                 ✓
Pointers   -                ✓                 ✓                 ✓
Token      7 days           30 days           90 days           365 days
 tracking
Cross-     -                -                 ✓                 ✓
 agent
Priority   -                -                 -                 ✓
 support

All tiers include Ebbinghaus decay, keyword retrieval, and file-based transparency.

Roadmap

• MCP server (tools + resources)
• REST API (Hindsight v1 compatible)
• Keyword retrieval + scoring
• Token economics tracking
• Ebbinghaus decay
• Memory consolidation
• x402 micropayments
• SSE transport for MCP
• Cloud sync
• Knowledge graph

Why Not Hindsight?

Hindsight is powerful but expensive: it calls LLMs for every recall/retain, uses PostgreSQL + pgvector, and requires a running daemon. Nexus achieves comparable retrieval quality at 8% of the token cost — no LLM calls, no database, no daemon. Just files and algorithms.

Why Not Mem0/Letta/Memoria?

Those are excellent systems, but they're architecturally heavy (vector DBs, embeddings, graph stores). Nexus is designed for the 80% use case: fast keyword retrieval with smart ranking. When you need semantic search, Nexus pointers bridge the gap at zero marginal cost.

No database. No API keys. No Docker. Just python nexus_mcp.py.

Built with ❤️ for the Hermes agent ecosystem.