# AgentMemo MCP Server

> Persistent memory and human-in-the-loop approval for AI agents via Model Context Protocol (MCP)

**AgentMemo** is a Model Context Protocol (MCP) server that gives AI agents persistent memory across sessions and human approval capabilities before sensitive actions.

## Features

- 🧠 **Persistent Memory** — Store and retrieve memories across conversations and sessions
- ✅ **Human Approval Gateway** — Agents can request approval from humans before critical actions
- 🔌 **MCP-Native** — Works with any MCP client (Claude Desktop, Cursor, Windsurf, OpenClaw)
- 🌐 **Cloud API** — Powered by AgentMemo API (https://agentmemo.net)
- 📦 **Zero Setup** — Just add your API key, no server to deploy

## Installation

```bash
npm install agentmemo-mcp
```

Or install globally for MCP clients:

```bash
npm install -g agentmemo-mcp
```

## Quick Start

### 1. Get Your API Key

Sign up for a free API key at [agentmemo.net](https://agentmemo.net) — no credit card required.

### 2. Configure Your MCP Client

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "agentmemo": {
      "command": "npx",
      "args": ["agentmemo-mcp"],
      "env": {
        "AGENTMEMO_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

#### Cursor / Windsurf

Add to your settings:

```json
{
  "mcpServers": {
    "agentmemo": {
      "command": "npx",
      "args": ["agentmemo-mcp"],
      "env": {
        "AGENTMEMO_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

#### OpenClaw

Already integrated! Set `AGENTMEMO_API_KEY` in your `.env` or OpenClaw config.

### 3. Use the Tools

Your agent now has access to these tools:

- **`remember`** — Store a memory for later recall
- **`recall`** — Search stored memories by query
- **`forget`** — Delete a memory by ID
- **`list_memories`** — List recent memories in a namespace
- **`request_approval`** — Ask a human to approve an action
- **`check_approval`** — Check the status of an approval request

## API Reference

### Tool: `remember`

Store information for later recall.

```json
{
  "content": "User prefers dark mode and concise responses",
  "namespace": "user-preferences"
}
```

**Returns:** Memory ID, creation timestamp

### Tool: `recall`

Search across stored memories.

```json
{
  "query": "dark mode preferences",
  "namespace": "user-preferences",
  "limit": 5
}
```

**Returns:** List of matching memories with scores

### Tool: `request_approval`

Request human approval before a sensitive action.

```json
{
  "action": "Delete all emails older than 1 year",
  "context": "Freeing up 50GB of storage"
}
```

**Returns:** Approval request ID and status

### Tool: `check_approval`

Poll the status of a pending approval.

```json
{
  "id": "approval_12345"
}
```

**Returns:** Status (pending/approved/rejected) and decision if available

## Memory Namespaces

Organize memories by namespace to keep them separate:

- `user-preferences` — User settings and preferences
- `project-alpha` — Project-specific context
- `meeting-notes` — Meeting transcripts and summaries
- `custom/any-name` — Any custom namespace

## Development

### Requirements

- Node.js 18+
- npm 9+

### Setup

```bash
git clone https://github.com/andrewpetecoleman-cloud/agentmemo-mcp.git
cd agentmemo-mcp
npm install
```

### Testing

```bash
npm test
```

### Building

```bash
npm run build
```

## How It Works

1. **Agent asks for memory** — "Remember that the user prefers dark mode"
2. **MCP Server handles it** — Calls AgentMemo API with your API key
3. **Memory is stored** — Persisted in AgentMemo cloud (encrypted in transit)
4. **Agent recalls later** — "What are the user's preferences?"
5. **Memory is retrieved** — Searched from AgentMemo and returned to agent

For approvals, the agent pauses and waits for human decision before proceeding.

## Architecture

```
Agent (Claude/GPT/etc)
    ↓
MCP Server (agentmemo-mcp)
    ↓
AgentMemo API (agentmemo.net)
    ↓
Memory Storage + Approval Gateway
```

## Pricing

**Free Tier:**
- 10,000 memories
- 100 searches/day
- No credit card required

**Paid Plans:**
- Starter: $19/month
- Pro: $99/month
- Team: $499/month

See [agentmemo.net](https://agentmemo.net) for full pricing.

## Security

- ✅ HTTPS encrypted in transit
- ✅ API key authentication
- ✅ Namespace isolation
- ✅ No data sharing with third parties
- ✅ User data never used for model training

## Support

- 📖 Docs: [agentmemo.net/docs](https://agentmemo.net/docs)
- 💬 Email: [hello@agentmemo.net](mailto:hello@agentmemo.net)
- 🐛 Issues: [GitHub Issues](https://github.com/andrewpetecoleman-cloud/agentmemo-mcp/issues)

## License

MIT

## Contributing

Contributions welcome! Please:

1. Fork this repo
2. Create a feature branch
3. Submit a pull request

## Related Projects

- [AgentMemo API](https://github.com/andrewpetecoleman-cloud/agentmemo) — Full product repo
- [TypeScript SDK](https://www.npmjs.com/package/agentmemo) — Node.js/browser SDK
- [Python SDK](https://pypi.org/project/agentmemo/) — Python integration

---

Built by [Andy Coleman](https://github.com/andrewpetecoleman-cloud) at [AgentMemo](https://agentmemo.net)