# genesys-memory MCP server

Open-source causal memory for AI agents: persistent, explainable, MCP-native memory (13 tools).

## At a glance

genesys-memory is an MCP server in the AI & Memory category. It runs locally over stdio via `uvx genesys-memory`, and needs OPENAI_API_KEY and ANTHROPIC_API_KEY. It exposes 13 tools, including memory_store, memory_amend and memory_recall. It scores A (83/100) on the MCP Skills Hub health score as of Oct 28, 2026.

## Install

### How to install genesys-memory in Claude Code

1. Add the server

```bash
claude mcp add genesys-memory -e 'OPENAI_API_KEY=<OPENAI_API_KEY>' -e 'ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>' -- uvx genesys-memory
```

2. Fill in your credentials

   Replace <OPENAI_API_KEY>, <ANTHROPIC_API_KEY> with your real values. Keep secrets out of any config file you commit.

3. Verify it's connected

```bash
claude mcp list
```

4. Sharing it with your team?

   Add `--scope project` to write it to .mcp.json in the repository root, which you can commit (with the secrets left as environment variables).

5. Use it in a session

   Ask Claude to use the tools this server exposes (e.g. memory_store, memory_amend, memory_recall). It discovers them automatically.

### How to install genesys-memory in Claude Desktop

1. Open your MCP config

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add this server

```json
{
  "mcpServers": {
    "genesys-memory": {
      "command": "uvx",
      "args": [
        "genesys-memory"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}
```

3. Fill in your credentials

   Replace <OPENAI_API_KEY>, <ANTHROPIC_API_KEY> with your real values. Keep secrets out of any config file you commit.

4. Restart Claude Desktop

   The tools appear under the 🔌 menu once the app reloads.

### How to install genesys-memory in Cursor

1. Create / edit .cursor/mcp.json in your project

```json
{
  "mcpServers": {
    "genesys-memory": {
      "command": "uvx",
      "args": [
        "genesys-memory"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}
```

2. Fill in your credentials

   Replace <OPENAI_API_KEY>, <ANTHROPIC_API_KEY> with your real values. Keep secrets out of any config file you commit.

3. Enable it

   Cursor Settings → MCP → toggle the server on. Tools become available to the Composer/Agent.

### How to install genesys-memory in Codex CLI

1. Add to ~/.codex/config.toml

```toml
[mcp_servers.genesys-memory]
command = "uvx"
args = ["genesys-memory"]
env = { OPENAI_API_KEY = "<OPENAI_API_KEY>", ANTHROPIC_API_KEY = "<ANTHROPIC_API_KEY>" }
```

2. Fill in your credentials

   Replace <OPENAI_API_KEY>, <ANTHROPIC_API_KEY> with your real values. Keep secrets out of any config file you commit.

3. Run Codex

   Codex loads MCP servers from config.toml on startup and exposes their tools to the agent.

### How to install genesys-memory in Windsurf

1. Edit ~/.codeium/windsurf/mcp_config.json

```json
{
  "mcpServers": {
    "genesys-memory": {
      "command": "uvx",
      "args": [
        "genesys-memory"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}
```

2. Fill in your credentials

   Replace <OPENAI_API_KEY>, <ANTHROPIC_API_KEY> with your real values. Keep secrets out of any config file you commit.

3. Reload

   Windsurf → Cascade → refresh MCP servers. Cascade can now call the tools.

### How to install genesys-memory in Cline

1. Open Cline → MCP Servers → Configure

   Adds to cline_mcp_settings.json.

2. Add the server

```json
{
  "mcpServers": {
    "genesys-memory": {
      "command": "uvx",
      "args": [
        "genesys-memory"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}
```

3. Fill in your credentials

   Replace <OPENAI_API_KEY>, <ANTHROPIC_API_KEY> with your real values. Keep secrets out of any config file you commit.

### How to install genesys-memory in VS Code

1. Create .vscode/mcp.json

```json
{
  "servers": {
    "genesys-memory": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "genesys-memory"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}
```

2. Fill in your credentials

   Replace <OPENAI_API_KEY>, <ANTHROPIC_API_KEY> with your real values. Keep secrets out of any config file you commit.

3. Start it

   VS Code shows a ▶ Start action above the server entry. Agent mode (Copilot Chat) can then use the tools.

## Tools

- `memory_store` — Store a new memory. Use `related` for writer-specified typed edges (`{id, type}`); `related_to` is legacy and always creates `caused_by`. Optional `category`. May return `possible_conflicts` (heuristic hints).
- `memory_amend` — Record a correction: creates a new memory that supersedes an existing one. The old memory is kept (decayed in recall), not deleted.
- `memory_recall` — Recall memories by natural language query (vector + keyword + graph spreading activation). Supports `verbosity: "concise"` for lightweight payloads.
- `memory_search` — Filtered vector search by status, category, date (`since`), last-active date (`active_since`), or entity. Pass an empty query to enumerate by recency instead (no embedder needed) — with `since`/`active_since` this answers "what's new since 
- `memory_traverse` — Walk the causal graph from a node. Returns reachable nodes and the edges of the induced subgraph (`source/target/type/weight/created_by`) — a superset of the BFS tree, so paths can be reconstructed. Honors `edge_types`.
- `memory_explain` — Explain a memory's score. Includes a `score_model` block (formula + live per-force breakdown + staleness note) and `removal_impact`.
- `memory_stats` — Get memory system statistics
- `pin_memory` — Pin a memory so it's never forgotten
- `unpin_memory` — Unpin a previously pinned memory
- `delete_memory` — Permanently delete a memory
- `list_core_memories` — List core memories, optionally filtered by category
- `set_core_preferences` — Set user preferences for core memory categories
- `promote_to_org` — Promote a private memory to org visibility

Source repository: https://github.com/Astrix-Labs/genesys

---

Source: https://mcp-skills-hub.vercel.app/mcps/io-github-astrix-labs-genesys-memory · MCP Skills Hub · data as of 2026-10-28T12:31:05Z