Nexus Memory System

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

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

Feature	Description
Zero dependencies	No database, no vector store, no embeddings API. Pure Python stdlib.
MCP native	5 tools (search, stats, save, touch, decay) + resource access
REST API	Hindsight v1 compatible. Drop-in replace HINDSIGHT_API_URL.
Ebbinghaus decay	Automatic forgetting curve. Memories expire on schedule.
Token economics	92% cost reduction vs Hindsight. Built-in token tracking.
Pointer-based RAG	Kronos-style 300-token pointers for budgeted context assembly.
File-based	Plain markdown files. Readable, editable, git-versionable.
Bilingual	Full Chinese + English support.
Cross-agent sharing	Share memories across Hermes agents or any MCP client.

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

Tier	Decay	Purpose
Working	7 days	In-session context
Episodic	30 days	Past experiences
Semantic	90 days	Facts, preferences
Procedural	180 days	Workflows, skills
Reflections	60 days	Meta-cognition
Core	Never	Identity, rules

Token Economics

Metric	Hindsight	Nexus	Savings
Per recall	500 tokens	30 tokens	94%
Per retain	300 tokens	50 tokens	83%
5 agents/day	440,000 tokens	36,000 tokens	92%
Monthly cost	$39.60	$3.24	$36.36

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

• [x] MCP server (tools + resources)
• [x] REST API (Hindsight v1 compatible)
• [x] Keyword retrieval + scoring
• [x] Token economics tracking
• [x] Ebbinghaus decay
• [x] 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.