Skip to main content
Glama
Y-Sky-bro

nexus-memory

by Y-Sky-bro
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Nexus Memory System

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

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.

Related MCP server: Memory Search MCP Server

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

  • 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.

Available Tools

5 tools
decayA

Run a dry-run decay check. Calculates Ebbinghaus decay for all memories and reports which would be archived. Does NOT modify any files.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It explicitly states 'Does NOT modify any files,' which is critical for behavioral transparency. However, it lacks details on performance or other potential side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the verb 'Run a dry-run decay check,' and every word adds value. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains the tool's action and result (reports which memories would be archived). For a zero-parameter tool, this is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters, so baseline is 4. The description adds no parameter information, which is acceptable since none exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs a dry-run decay check, calculates Ebbinghaus decay for all memories, and reports which would be archived. It explicitly distinguishes itself from siblings by emphasizing it does not modify files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The term 'dry-run' implies a preview before actual archiving, but no explicit guidance on when to use versus alternatives is given. Since sibling tools (save, search, stats, touch) serve different purposes, the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

saveB

Save a new memory to a specified tier. Creates a markdown file with frontmatter. Use for recording new information, preferences, or experiences.

ParametersJSON Schema
NameRequiredDescriptionDefault
tierYesMemory tier: episodic (experiences), semantic (facts/preferences), procedural (workflows), reflection (meta), working (in-session)
nameYesFilename slug (no extension, use dashes: my-memory-name)
contentYesFull markdown content of the memory (including title heading)
tagsNoComma-separated tags (optional)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry full behavioral disclosure. It mentions file creation and markdown format but omits side effects, permissions, or changes to existing data. The agent lacks critical safety context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences are efficient and front-loaded with the main action. Every sentence adds value without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 parameters and no output schema, the description covers the basic purpose and usage but lacks details on return value, error handling, and edge cases. It is adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions for each parameter. The description adds minimal extra meaning beyond 'creates a markdown file with frontmatter,' which does not significantly enhance parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it saves a new memory to a tier and creates a markdown file with frontmatter. It is specific about the verb ('Save') and resource ('a new memory'), though it does not explicitly differentiate from sibling tools like decay or search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a use case ('Use for recording new information, preferences, or experiences') but lacks instructions on when not to use or explicit alternatives among siblings. Usage is implied rather than clearly bounded.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statsA

Show memory health statistics: file counts per tier, average strength, active/decaying/archived counts.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It describes the tool as displaying statistics, which implies a read-only, non-destructive operation. However, it does not explicitly confirm safety, permissions, or side effects, leaving some ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently communicates the tool's function without extraneous words. Every part contributes to understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the zero parameters and no output schema, the description is sufficiently complete. It conveys the scope of the tool. However, mentioning the output format (e.g., JSON) could add minor value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the baseline is 4. The description adds value by listing specific statistics shown, which is more informative than the empty schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Show' and identifies the resource as 'memory health statistics', listing concrete outputs (file counts per tier, average strength, active/decaying/archived counts). This clearly distinguishes the tool from siblings like decay, save, search, and touch, which perform different actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives. It implies an overview function but does not state when to prefer stats over search or other sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

touchA

Boost a memory's strength (simulate access, counteracts Ebbinghaus decay). Use this when a memory is referenced or found relevant.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesMemory filename (with or without .md extension)
boostNoStrength boost amount (default 0.15, max 1.0)

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that the tool simulates access and counteracts decay, and mentions default boost values. However, without annotations, lacks details on persistence, side effects, or whether modification is permanent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the primary action, no redundant or missing words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose and usage well for a simple tool with two parameters. Lacks return value description (no output schema), but the missing info is minor given tool simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for both parameters (name and boost). The description adds purpose context but does not enhance parameter semantics beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies a clear action ('Boost a memory's strength') and resource ('memory'), with context about counteracting Ebbinghaus decay. This distinguishes it from siblings like 'decay' and 'save'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises when to use ('when a memory is referenced or found relevant'), implying contrast with decay. Does not explicitly state when not to use or list alternatives, but the guidance is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a unique and clearly defined purpose: decay for dry-run archiving, save for creating new memories, search for retrieval, stats for health metrics, and touch for strength boosting. No overlap exists.

Naming Consistency5/5

All tool names are single, imperative verbs (decay, save, search, stats, touch), forming a consistent and predictable pattern. 'Stats' is a noun but functions as a command verb in this context.

Tool Count5/5

With 5 tools, the set covers core memory operations (create, read, update, delete via decay/archiving, and health monitoring) without unnecessary bloat. The count is well-scoped for the server's purpose.

Completeness4/5

The tool surface covers creation, retrieval, strength management, decay checking, and statistics. A minor gap is the lack of an explicit 'forget' or 'delete' tool, but decay archives memories, and users can boost strength. The set is largely complete for typical memory management workflows.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Y-Sky-bro/nexus-memory'

If you have feedback or need assistance with the MCP directory API, please join our Discord server