io.github.helinakdogan/agent-magnet

Your AI forgets every user the moment the session ends.
Magnet fixes that — without changing your code.

How It Works

User sends message → Magnet injects memory → LLM responds → Magnet learns

• Learns from corrections, rejections, and implicit patterns — not just conversations
• Builds a persistent profile that improves with every interaction
• Knows what to forget: permanent, contextual, and transient signals decay at different rates
• Cross-user learning: patterns from one user improve cold-start for the next

Two Ways to Integrate

1. Proxy Mode — zero code changes

Works with OpenAI, Anthropic, Google Gemini, and any OpenAI-compatible client.

from openai import OpenAI

client = OpenAI(
    api_key="mg_sk_...",
    base_url="https://magnet-gateway.onrender.com/v1",
    default_headers={"x-session-id": "user_123"}
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",  # or anthropic/claude-haiku-4-5, google/gemini-flash
    messages=[{"role": "user", "content": "Hello"}]
)

Get your API key: agentmagnet.app

2. MCP Server — self-hosted, your data stays with you

Works with Claude Desktop, Cursor, and any MCP client.

pip install agent-magnet

{
  "mcpServers": {
    "agent-magnet": {
      "command": "agent-magnet-mcp",
      "env": {
        "MAGNET_REDIS_URL": "your_redis_url",
        "MAGNET_OPENAI_KEY": "your_openai_key"
      }
    }
  }
}

MCP tools available:

• get_profile — get the learned memory profile for a user
• inject_memory — get a memory string ready to inject into system prompt
• add_signal — record a behavioral signal (correction, rejection, preference)
• get_cold_start — get an onboarding profile for a new user based on aggregate patterns

3. SDK Mode — deep integration

pip install agent-magnet

from magnet import BehavioralMemory

memory = BehavioralMemory(reflector_model="openai/gpt-4o-mini")

context = memory.get_injection(user_id="alice")
memory.add(messages, user_id="alice")

Why Magnet

Architecture

Three memory layers — each one builds on the last.

Layer 1 — Behavioral (Redis)
Always on, zero latency. Learns preferences, corrections, and rejections in real time. Signals decay by type: permanent (e.g. "hates mushrooms"), contextual (e.g. "prefers bullet lists"), transient (e.g. "wants short answers today").

Layer 2 — Episodic (Qdrant)
Semantic recall from past sessions. Triggered only when relevant — no bloat, no noise.

Layer 3 — Knowledge (Neo4j)
Long-term entity relationships. PREFERRED_BY, REJECTED_BY, EXPECTED_BY — structured understanding of who the user is.

Consolidation Engine
Runs every 24 hours. Extracts cross-user patterns anonymously. New users don't start from zero.

Configuration

Documentation

Full docs at agentmagnet.app/docs

Claude Code Setup

How it works end-to-end:

• Session start — Claude automatically reads your memory profile and uses it
• During the session — Claude learns from your corrections, preferences, and rejections
• Session end — a Stop hook saves everything to Redis before Claude Code closes

Step 1 — Install

pipx install agent-magnet

Get a free Redis URL at upstash.com (takes 1 minute).

Step 2 — Add the Stop hook and MCP server

In ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "MAGNET_REDIS_URL=your_redis_url MAGNET_OPENAI_KEY=your_openai_key MAGNET_USER_ID=your_name MAGNET_PROJECT_ID=default /path/to/pipx/venvs/agent-magnet/bin/python -m magnet.hooks.save_session",
          "timeout": 10
        }]
      }
    ]
  },
  "mcpServers": {
    "agent-magnet": {
      "command": "agent-magnet-mcp",
      "env": {
        "MAGNET_REDIS_URL": "your_redis_url",
        "MAGNET_OPENAI_KEY": "your_openai_key",
        "MAGNET_USER_ID": "your_name",
        "MAGNET_PROJECT_ID": "default"
      }
    }
  }
}

To find your pipx Python path: pipx environment | grep PIPX_HOME
Then the full path is: {PIPX_HOME}/venvs/agent-magnet/bin/python

Step 3 — Tell Claude to load memory automatically

Create ~/.claude/CLAUDE.md (global instructions Claude reads at the start of every session):

# Memory

At the start of every conversation, call the `inject_memory` MCP tool (agent-magnet) with:
- user_id: "your_name"
- project_id: "default"

Use the returned memory profile as context for the conversation.

This is the critical step. Without it, memory is saved but never loaded into the conversation.

Step 4 — Restart Claude Code

That's it. From now on:

• Every new conversation starts with your memory profile loaded
• Every closed session is saved automatically
• No manual commands needed

Use the same MAGNET_USER_ID across Claude Code, Cursor, and Codex to share memory between tools.

What you can say during a session

Memory loads automatically at the start, but Claude doesn't always proactively record things mid-session. These phrases work reliably:

You don't need exact phrasing — Claude understands intent and will call the right MCP tool. But if it doesn't, these always work.

Cursor Setup

Option A — MCP (automatic load, manual save)

Cursor doesn't support Stop hooks, so sessions must be saved manually.

1. Install: pipx install agent-magnet
2. Get a free Redis URL at upstash.com
3. Add to Cursor MCP config (Settings → MCP):

{
  "mcpServers": {
    "agent-magnet": {
      "command": "agent-magnet-mcp",
      "env": {
        "MAGNET_REDIS_URL": "your_redis_url",
        "MAGNET_OPENAI_KEY": "your_openai_key",
        "MAGNET_USER_ID": "your_name",
        "MAGNET_PROJECT_ID": "default"
      }
    }
  }
}

4. Add to Cursor Rules (Settings → Rules for AI):

At the start of every conversation, call the inject_memory MCP tool (agent-magnet) with user_id="your_name" and project_id="default". Use the result as context.

Important: MCP tools only work in Agent mode. In Ask mode, Cursor blocks tool calls. Switch to Agent mode for memory to load and save correctly.

5. At the end of a session, type: save this session to my memory

Use the same MAGNET_USER_ID as Claude Code — memory is shared across tools.

Option B — Proxy (fully automatic)

1. Go to Cursor Settings → Models
2. Set "Override OpenAI Base URL" to: https://magnet-gateway.onrender.com/v1
3. Enter your Agent Magnet API key from agentmagnet.app
4. Add header: x-magnet-user-id: your_name

Every request automatically saves and recalls memory. No manual commands, no setup beyond this.

Contributing

• Issues: Report a bug or request a feature
• X: @AgentMagnetAI

If Magnet saved you from a bad context window, give it a ⭐

License

MIT — see LICENSE. Built by Agent Magnet.