# agent-magnet

This MCP server carries project context between sessions and AI tools. Use it for decisions, conventions, preferences, and past attempts.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 14
- Author: helinakdogan
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/helinakdogan/agentmagnet
- Updated: 2026-09-05
- HTML: https://affpapa.org/en/nevibecode/mcp/agent-magnet

## What it does

agent-magnet gives AI coding tools a persistent behavioral memory. It records project decisions, conventions, cautions, goals, preferences, failed approaches, and completed actions, then organizes those records for later use. The same memory can serve Claude, Cursor, and Codex.

The local setup starts with `pip install agent-magnet` followed by `agent-magnet init`. That command configures Claude Code, Claude Desktop, and Cursor. Codex and other MCP clients can use a manual setup with `agent-magnet-mcp` and the `MAGNET_USER_ID` environment variable.

Local operation needs no key. Team memory does require a paid Agent Magnet key. Configuration may also include `MAGNET_OPENAI_KEY`, `MAGNET_LOCAL_MODE`, `MAGNET_REDIS_URL`, and `MAGNET_PROJECT_ID`.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `MAGNET_USER_ID`, `MAGNET_OPENAI_KEY`, `MAGNET_LOCAL_MODE`, `MAGNET_REDIS_URL`, `MAGNET_PROJECT_ID` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env MAGNET_USER_ID=<MAGNET_USER_ID> --env MAGNET_OPENAI_KEY=<MAGNET_OPENAI_KEY> --env MAGNET_LOCAL_MODE=<MAGNET_LOCAL_MODE> --env MAGNET_REDIS_URL=<MAGNET_REDIS_URL> --env MAGNET_PROJECT_ID=<MAGNET_PROJECT_ID> --transport stdio agent-magnet -- uvx agent-magnet
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-magnet <command>

### Codex

**Platform CLI**
```bash
codex mcp add agent-magnet --env MAGNET_USER_ID=<MAGNET_USER_ID> --env MAGNET_OPENAI_KEY=<MAGNET_OPENAI_KEY> --env MAGNET_LOCAL_MODE=<MAGNET_LOCAL_MODE> --env MAGNET_REDIS_URL=<MAGNET_REDIS_URL> --env MAGNET_PROJECT_ID=<MAGNET_PROJECT_ID> -- uvx agent-magnet
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-magnet <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "agent-magnet": {
            "command": "uvx",
            "args": [
                "agent-magnet"
            ],
            "env": {
                "MAGNET_USER_ID": "<MAGNET_USER_ID>",
                "MAGNET_OPENAI_KEY": "<MAGNET_OPENAI_KEY>",
                "MAGNET_LOCAL_MODE": "<MAGNET_LOCAL_MODE>",
                "MAGNET_REDIS_URL": "<MAGNET_REDIS_URL>",
                "MAGNET_PROJECT_ID": "<MAGNET_PROJECT_ID>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-magnet <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "agent-magnet": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "agent-magnet"
            ],
            "env": {
                "MAGNET_USER_ID": "<MAGNET_USER_ID>",
                "MAGNET_OPENAI_KEY": "<MAGNET_OPENAI_KEY>",
                "MAGNET_LOCAL_MODE": "<MAGNET_LOCAL_MODE>",
                "MAGNET_REDIS_URL": "<MAGNET_REDIS_URL>",
                "MAGNET_PROJECT_ID": "<MAGNET_PROJECT_ID>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-magnet <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MAGNET_USER_ID=<MAGNET_USER_ID> -e MAGNET_OPENAI_KEY=<MAGNET_OPENAI_KEY> -e MAGNET_LOCAL_MODE=<MAGNET_LOCAL_MODE> -e MAGNET_REDIS_URL=<MAGNET_REDIS_URL> -e MAGNET_PROJECT_ID=<MAGNET_PROJECT_ID> agent-magnet uvx agent-magnet
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-magnet <command>

## When to use it
- carry project decisions into new sessions
- share context across Claude, Cursor, and Codex
- record conventions and team preferences
- remove stale memories after work is complete
- connect persistent context to an MCP client

## Example prompts
- Remember that this project uses `PostgreSQL` for persistence.
- Store the rule that API handlers belong in `src/api`.
- Forget the outdated warning about `legacy-auth`.

## Similar
- [lead-magnet-generator](https://affpapa.org/en/nevibecode/skills/lead-magnet-generator.md) — skill · 1200 installs
- [lead-magnet](https://affpapa.org/en/nevibecode/skills/lead-magnet.md) — skill · 452 installs
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89609
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74569
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89899

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md