Agent Memory

Overview

BotCreds Agent Memory gives AI agents a persistent memory layer backed by WordPress. Instead of rebuilding context from scratch on every session, agents can write to and read from a shared, durable knowledge store.

It runs in two modes depending on whether you supply an OpenAI API key:

Agents interact through a standard REST API or a built-in MCP JSON-RPC endpoint — compatible with Claude Desktop, Claude Code, and any MCP-capable client. The agent never needs to know about embeddings; it just queries in plain language and gets ranked results back.

Requirements

• WordPress 6.0 or later
• PHP 7.4 or later
• MySQL 5.7+ or MariaDB 10.3+
• HTTPS recommended for REST API access
• Vector mode only: OpenAI API key with access to text-embedding-3-small

Installation

From WordPress.org (recommended)

Once approved on WP.org, install directly from your WordPress dashboard:

1. Open the plugin installer

   In your WordPress admin, go to Plugins → Add New Plugin.

2. Search for BotCreds Agent Memory

   Type botcreds-agent-memory in the search box and click Install Now.

3. Activate

   Click Activate. The plugin creates its database table automatically on first activation.

Manual install (GitHub)

# Download and unzip
curl -L https://github.com/joesbobclaw/botcreds-agent-memory/archive/refs/heads/main.zip -o agent-memory.zip
unzip agent-memory.zip -d wp-content/plugins/botcreds-agent-memory

# Or via WP-CLI
wp plugin install https://github.com/joesbobclaw/botcreds-agent-memory/archive/main.zip --activate

Configuration

After activation, go to Settings → Agent Memory in your WordPress admin.

KV Mode (no API key)

Works out of the box. No configuration required. All entries are stored as plain text with optional namespace tagging. Retrieval is exact-match or filtered-list — no semantic search.

Vector Mode (OpenAI)

Add your OpenAI API key to enable semantic search.

// Optional: define in wp-config.php instead of the settings UI
define('BOTCREDS_OPENAI_KEY', 'sk-...');

Once the key is saved, new entries are automatically embedded on write. To embed existing entries, use the Re-index all button in the settings page or call the /reindex endpoint (admin only).

Authentication

The REST API uses WordPress Application Passwords for authentication. All write operations (POST, DELETE) require authentication. GET requests are public by default but can be restricted via the settings page.

Generate credentials

1. Open your user profile

   In WordPress admin, go to Users → Profile.

2. Add an Application Password

   Scroll to the Application Passwords section. Enter a name (e.g., my-agent) and click Add New Application Password.

3. Copy the generated password

   It’s shown once. Store it securely.

Using the credentials

curl -u "username:app-password" \
     -H "Content-Type: application/json" \
     https://yoursite.com/wp-json/botcreds-memory/v1/entries

Authorization: Basic <base64(username:password)>

REST API Reference

Base URL: https://yoursite.com/wp-json/botcreds-memory/v1

GET /wp-json/botcreds-memory/v1/entries?namespace=project:clawpress&per_page=10

[
  {
    "id": 42,
    "key": "deploy-checklist",
    "value": "Run plugin check, activate, test REST API, update changelog",
    "namespace": "project:clawpress",
    "embedding_model": "text-embedding-3-small",
    "created_at": "2026-06-04T22:14:33Z",
    "updated_at": "2026-06-04T22:14:33Z"
  }
]

POST /wp-json/botcreds-memory/v1/entries
Content-Type: application/json
Authorization: Basic <credentials>

{
  "key": "deploy-checklist",
  "value": "Run plugin check, activate, test REST API, update changelog",
  "namespace": "project:clawpress"
}

{
  "id": 42,
  "key": "deploy-checklist",
  "value": "Run plugin check, activate, test REST API, update changelog",
  "namespace": "project:clawpress",
  "embedding_model": "text-embedding-3-small",
  "created_at": "2026-06-04T22:14:33Z",
  "updated_at": "2026-06-04T22:14:33Z"
}

GET /wp-json/botcreds-memory/v1/entries/42

{
  "id": 42,
  "key": "deploy-checklist",
  "value": "Run plugin check, activate, test REST API, update changelog",
  "namespace": "project:clawpress",
  "embedding_model": "text-embedding-3-small",
  "created_at": "2026-06-04T22:14:33Z",
  "updated_at": "2026-06-04T22:14:33Z"
}

DELETE /wp-json/botcreds-memory/v1/entries/42
Authorization: Basic <credentials>

{
  "deleted": true,
  "id": 42
}

POST /wp-json/botcreds-memory/v1/search
Content-Type: application/json
Authorization: Basic <credentials>

{
  "query": "how do I deploy the plugin?",
  "limit": 3,
  "namespace": "project:clawpress"
}

{
  "results": [
    {
      "id": 42,
      "key": "deploy-checklist",
      "value": "Run plugin check, activate, test REST API, update changelog",
      "namespace": "project:clawpress",
      "similarity": 0.924
    }
  ],
  "mode": "vector",
  "query": "how do I deploy the plugin?"
}

MCP Integration

BotCreds Agent Memory exposes a JSON-RPC 2.0 endpoint that is fully compatible with the Model Context Protocol (MCP). This lets Claude Desktop, Claude Code, and other MCP-capable clients call memory tools natively — no REST knowledge required on the agent side.

MCP endpoint URL:

https://yoursite.com/wp-json/botcreds-memory/v1/mcp

Claude Desktop Setup

Add the following to your Claude Desktop MCP config file:

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": [
        "-y",
        "@botcreds/mcp-bridge",
        "--url",
        "https://yoursite.com/wp-json/botcreds-memory/v1/mcp",
        "--auth",
        "username:app-password"
      ]
    }
  }
}

Restart Claude Desktop after saving the config file. The memory tools will appear in Claude’s tool list automatically.

Claude Code Setup

Add to your project’s .mcp.json or run via the CLI:

{
  "servers": {
    "agent-memory": {
      "type": "http",
      "url": "https://yoursite.com/wp-json/botcreds-memory/v1/mcp",
      "headers": {
        "Authorization": "Basic <base64(username:password)>"
      }
    }
  }
}

claude --mcp-server "agent-memory=https://yoursite.com/wp-json/botcreds-memory/v1/mcp"

MCP Tools Reference

Once connected, the following tools are available to the agent:

Data Model

Entries are stored in the wp_botcreds_memory custom table.

Error Codes

Changelog