# NEXUS — full reference for AI agents

> Persistent memory and cognition for AI agents over MCP. This file has everything an agent needs to connect and work with NEXUS in a single request. Short version: https://nexus.eblas.link/llms.txt

## What NEXUS is

NEXUS stores what an agent learns — decisions, preferences, facts about projects, what happened in each session — in a knowledge graph that lives outside the context window. All agents of an account (Claude Code, Claude, ChatGPT, Cursor, custom MCP or REST clients) read and write the same memory, so what one learns the others know.

Key properties:
- Memory types: episodic (what happened), semantic (timeless facts), procedural (how to do things), working memory (session context).
- Hybrid retrieval: dense embeddings plus lexical matching.
- Validity: every memory declares whether it narrates an event (true forever), describes a state (expires when it changes) or is a pending item (expires when done). Superseded memories point to what replaced them.
- Epistemic source: a memory can declare whether it was measured, inferred or reported.
- World graph: entities and relations with evidence and temporal validity; contradictions between relations are detected; duplicate entities are merged reversibly.
- Reasoning: rules and inference with explanations, hypotheses evaluated against evidence, metacognitive health checks.
- Work: goals with progress, tasks, reusable procedures, agent-to-agent messaging.
- Isolation: each account (tenant) is isolated with PostgreSQL row-level security; each agent has its own revocable credential.

## Connecting

MCP endpoint (Streamable HTTP): https://nexus.eblas.link/mcp

Authentication is required:
- OAuth 2.1 (clients like Claude and ChatGPT): authorization code with PKCE S256, dynamic client registration (RFC 7591), public clients. Scopes: memoria, grafo, cognicion, trabajo.
  - Protected resource metadata: https://nexus.eblas.link/.well-known/oauth-protected-resource
  - Authorization server metadata: https://nexus.eblas.link/.well-known/oauth-authorization-server
  - Endpoints: /oauth/authorize, /oauth/token, /oauth/register, /oauth/revoke
- Agent credential (Claude Code, Cursor, scripts): `nxa_...` token issued by the account owner in the console, sent as `Authorization: Bearer nxa_...`. Save it to `~/.config/nexus/token` or export `NEXUS_TOKEN` so the hooks can use it.

Claude Code:
    claude mcp add --transport http nexus-agi https://nexus.eblas.link/mcp --header "Authorization: Bearer nxa_..."

JSON (Claude Desktop, Cursor .cursor/mcp.json, generic MCP clients):
    {"mcpServers": {"nexus-agi": {"type": "http", "url": "https://nexus.eblas.link/mcp", "headers": {"Authorization": "Bearer nxa_..."}}}}

REST: https://nexus.eblas.link/api/v1 with the same Bearer credential. Always send a custom User-Agent (Cloudflare blocks Python-urllib's default with 403, error 1010). Check: `curl -A nexus-hooks/1.0 -H "Authorization: Bearer <token>" https://nexus.eblas.link/api/v1/metacognition/health` → 200.

## Setup (optional, for agents on the user's machine)

For Claude Code or Cursor, `get_setup_kit()` (Cursor: `client="cursor"`) returns the SessionStart, UserPromptSubmit and Stop hooks plus an idempotent bash installer that writes ~/.claude/hooks/*, merges the hooks block into ~/.claude/settings.json and imports the usage policy into CLAUDE.md. Installing changes files on the user's machine, so it is the user's decision; the agent can offer it. With the hooks, memory is recalled and stored automatically; without them NEXUS only has what the agent stores through its tools. Chat clients (Claude web or desktop, ChatGPT) don't use hooks; there, recall depends on instructions the user pastes into the client: call `retrieve_memories` every turn with the user's message and `time_range="all_time"`, decide any `duda_de_fusion` with `decide_merge_proposal` before answering, and store what was learned with `process_observation` (full text: https://nexus.eblas.link/documentacion, section 4).

## How to use it well

- Start of a session: `get_cognitive_health()` and `list_goals(status="active")`.
- Store new information: `process_observation(content, entity_hints, relations)` — stores the episode, resolves entities and links them in one call.
- Timeless truth: `store_fact`. Something that happened: `store_episode` (declare `volatilidad`: evento | estado | pendiente).
- Recall: `retrieve_memories(query, limit≈50)` in natural language, or `cognitive_query(topic)` for everything NEXUS knows about a topic.
- After many writes: `run_cognitive_cycle()`.
- Graph: `relate_entities(source_name, target_name, relation_type)` upserts both ends; elsewhere entities are UUIDs — use `search_entities` first.
- Correct stale knowledge with `supersede_memory` instead of storing a contradicting duplicate.

## MCP tools (grouped)

- Identity and setup: whoami, get_setup_kit
- Composite: process_observation, cognitive_query, run_cognitive_cycle, create_entity_cognitive
- Memory: store_episode, store_fact, retrieve_memories, supersede_memory, get_facts_by_entity, get_entity_episodes, push_context, get_context
- World graph: create_entity, update_entity, get_entity, list_entities, search_entities, create_relation, relate_entities, end_relation, ratify_relation, get_entity_relations, get_entity_neighbors, get_entity_graph_context, query_world_model, get_world_model_stats, get_ontology, strengthen_world_model
- Contradictions, merges and questions for the user: resolve_contradiction, get_merge_question, decide_merge_proposal, get_next_question, answer_question
- Reasoning: create_rule, list_rules, affirm_rule, generate_hypothesis, list_hypotheses, evaluate_hypothesis, get_cognitive_health
- Procedures: store_procedure, list_procedures, get_procedure, match_procedures, update_procedure, delete_procedure, record_procedure_usage
- Goals and planning: create_goal, activate_goal, pause_goal, close_goal, update_goal, list_goals, get_goal, report_goal_measurement, get_agent_tasks, complete_agent_task, get_planning_requests, submit_goal_plan, get_pending_work
- Tasks: create_task, list_tasks, get_task, update_task, complete_task, add_task_comment, delete_task
- Agent messaging: list_agents, send_message, read_messages, get_message_thread, messaging_preferences

## Access and plans

Without an account an agent cannot complete OAuth. Sign-up is open, no invite needed: https://nexus.eblas.link/en/signup. The human enters their email and an account name and confirms with a 6-digit code sent to that email (or continues with Google, when offered). The free plan ("Gratuito") includes up to 150 new memories and 2 active agents per month, without URL or document ingestion; paid plans are optional. Sign-up is a human step confirmed by email, so there is no sign-up flow for agents — send your human that link.

## Legal

Operator: Satoshi Payments, S.A.S. de C.V., Mexico City, Mexico.
Terms: https://nexus.eblas.link/terminos (EN: /en/terms). Privacy: https://nexus.eblas.link/privacidad (EN: /en/privacy).