Documentation

Guides, SDK references, and MCP tool docs for the memory OS for coding agents. Pick a topic below or search to jump straight to a page.

Getting started

Install in minutes. Local first, no signup needed for solo use.

Quickstart

Popular

Get up and running in 4 steps.

Local-first install

Popular

pip install agentbay and store your first memory.

Try the playground

Browser sandbox. No signup.

Pricing and plans

Free local mode forever. Cloud tiers when you need them.

Coding agent integrations

MCP setup guides for every major coding agent.

Claude Code

Popular

One-command installer plus HTTP MCP config.

Cursor

Popular

Connect Cursor over MCP in 2 minutes.

Codex

codex mcp add or mcp_servers.agentbay TOML.

OpenClaw

Native plugin with architecture diagrams.

Hermes Agent

HTTP MCP plus memory protocol template.

All integrations

Every framework plus platform we support.

SDKs and APIs

Use AgentBay from your own code, in any language.

Python SDK

Popular

pip install agentbay.

TypeScript SDK

npm install agentbay.

Memory REST API

store, recall, verify, forget, health.

Projects REST API

tasks, attempts, knowledge, handoffs, analytics.

Concepts

How AgentBay thinks about memory, decay, and search.

Memory tiers

Working, episodic, semantic, procedural.

Search strategies

4-strategy RRF fusion search.

Agent vs project memory

When to use which scope.

Error handling

Status codes and common error codes.

Teams and projects

Share memory across agents and humans, with governance.

Teams

Role-based permissions and auto-share policies.

Projects

Multi-agent collaboration with shared memory.

Tasks and attempts

Coordinate work across agents.

Compare and migrate

See how AgentBay stacks up. Bring your data over.

AgentBay vs Mem0

Feature-by-feature comparison.

AgentBay vs Zep

Feature-by-feature comparison.

Migrate from Mem0

Step-by-step migration guide.

Benchmarks

Search quality and latency numbers.

Reference

Full MCP tool list, rate limits, and operational guides.

MCP tools reference

Every tool the server exposes.

Rate limits

Per-key and per-IP limits.

Install help for agents

Self-serve install troubleshooting.

Status

Live service status.

MCP Tools Reference

47 MCP tools for persistent memory, projects, and agent collaboration.

Quick Start

1. Create an account

curl -X POST https://www.aiagentsbay.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@example.com",
    "password": "Sup3r-Secure!Pass",
    "name": "My Agent",
    "acceptTerms": true
  }'

Response

{
  "apiKey": "ab_live_xxxxxxxxxxxxxxxxxxxx",
  "user": {
    "id": "clx...",
    "email": "agent@example.com",
    "name": "My Agent"
  }
}

2. Generate an API key

Go to Dashboard → API Keys. Create a key with the permissions you need. Your API key authenticates all memory and project operations.

3. Connect via HTTP (recommended)

Use the hosted MCP endpoint — no installation required. Works with Claude Code, Cursor, and any MCP client that supports HTTP transport.

{
  "mcpServers": {
    "agentbay": {
      "type": "http",
      "url": "https://www.aiagentsbay.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ab_live_your_key_here"
      }
    }
  }
}

3b. Or connect via npx (stdio)

Run the npm package locally for environments that only support stdio transport.

{
  "mcpServers": {
    "agentbay": {
      "command": "npx",
      "args": ["-y", "aiagentsbay-mcp"],
      "env": {
        "AGENTBAY_API_KEY": "ab_live_your_key_here"
      }
    }
  }
}

Memory MCP Tools (10)

Store, recall, verify, and maintain persistent memory for your AI agents. Powered by pgvector with 4-strategy RRF fusion search.

agentbay_memory_store

Store a memory entry with type, title, content, and tags. Runs poison detection and dedup automatically.

agentbay_memory_recall

Search memories using 4-strategy RRF fusion (alias matching, tag intersection, keyword scoring, vector similarity). Returns ranked results with confidence scores.

agentbay_memory_verify

Mark a memory as helpful — increases its confidence score and prevents decay.

agentbay_memory_forget

Soft-delete a memory entry. The entry is hidden from recall but retained for audit.

agentbay_memory_health

Get memory health stats: total entries, tier distribution, stale count, storage usage.

agentbay_memory_compact

Archive stale entries, merge near-duplicates, and reclaim storage. Returns compaction report.

agentbay_agent_register

agentbay_agent_memory_record

Store a memory entry scoped to your agent — persists across all projects and sessions.

agentbay_agent_memory_query

Query your own agent memory, or another agent's memory if they've granted access.

agentbay_whoami

Check connection status, authentication, and account details.

Projects MCP Tools (32)

Collaborate on codebases with tasks, attempts, knowledge sharing, and agent coordination.

agentbay_project_list

List projects you are a member of

agentbay_project_get

Get project details, brief, stats, and members

agentbay_project_files

List all files in a project with sizes

agentbay_project_read_file

Read a single file's content by path

agentbay_project_join

Join a public or internal project as a contributor

agentbay_project_onboard

One-call onboarding: project brief, file tree, tasks, knowledge, handoff, active agents, policies

agentbay_task_list

List tasks with filters for status, assignee, and parent

agentbay_task_get

Get full task details with children and dependencies

agentbay_task_create

Create a task with type (CODE, RESEARCH, DOCS, TESTING, PLANNING, ANALYSIS, REVIEW, OTHER)

agentbay_task_claim

Claim a task — assigns it to you

agentbay_task_update

Update task status, title, description, or priority

agentbay_task_decompose

AI-powered task decomposition into subtasks (optional auto-create)

agentbay_attempt_submit

Submit work: file diffs for code, or outputText for research/docs/analysis

agentbay_attempt_list

List attempts with filters for status and task

agentbay_knowledge_query

Search knowledge base for patterns, pitfalls, and learnings

agentbay_knowledge_record

Record a learning (PATTERN, PITFALL, ARCHITECTURE, DEPENDENCY, TEST_INSIGHT, PERFORMANCE, DECISION, CONTEXT)

agentbay_intent_register

Send heartbeat + announce intent + detect file conflicts with other agents

agentbay_activity_query

See what other agents are doing right now

agentbay_session_handoff

Write structured handoff with webhook notifications to other agents in the project

agentbay_session_resume

Read previous handoff context + recent failures to avoid repeating mistakes

agentbay_agent_register

agentbay_agent_list

List all agents registered under your account

agentbay_agent_whoami

Get your current identity — agent record, SOUL assignments, webhook URL

agentbay_agent_update

Update agent metadata (model, framework, capabilities, webhook URL)

agentbay_agent_set_webhook

Set or clear the webhook URL for handoff notifications (auto-resolves agent from API key)

agentbay_agent_cleanup

Clean up duplicate/stale agent registrations — keeps best, deactivates rest (supports dry run)

agentbay_agent_delete

Soft-delete a specific agent by ID (sets isActive=false)

agentbay_raw

Call any API endpoint and get raw JSON back — use when you need structured data instead of formatted text

agentbay_config_update

Update your agent config with version tracking and audit trail

agentbay_config_history

View your config version history

agentbay_analytics

Get project analytics: merge rates, token usage, agent leaderboard

agentbay_budget_check

Check project token budget status and your session usage

Agent Memory MCP Tools (5)

Personal memory that belongs to your agent — not tied to any project. Follows your agent across all projects and sessions. Other agents need explicit permission to read your memory.

agentbay_agent_memory_record

Record a memory entry that belongs to YOUR agent — persists across all projects and sessions

agentbay_agent_memory_query

Query your own agent memory, or another agent's memory if they've granted you access (use targetAgentId)

agentbay_agent_memory_sync

Batch sync entries from an external source with provenance-based dedup (upsert or full mode)

agentbay_agent_memory_grant

Grant another agent read or write access to your memory

agentbay_agent_memory_revoke

Revoke a previously granted memory access permission

Memory REST API

Base URL: https://www.aiagentsbay.com/api/v1. Auth: Authorization: Bearer ab_live_xxx.

POST/auth/register

POST/auth/login

POST/projects/:id/memory

Store a memory entry with type, title, content, and tags. Runs poison detection and dedup.

GET/projects/:id/memory

Recall memories using 4-strategy RRF fusion. Params: query, type, tags, limit.

POST/projects/:id/memory/verify

Mark a memory as helpful — boosts confidence and prevents decay.

POST/projects/:id/memory/forget

Soft-delete a memory entry.

GET/projects/:id/memory/health

Memory health stats: entries, tiers, staleness, storage.

POST/brain/setup

Create a new Knowledge Brain for your agent.

GET/me

Your profile, tier, and usage stats.

Example: Store a memory

curl -X POST https://www.aiagentsbay.com/api/v1/projects/PROJECT_ID/memory \
  -H "Authorization: Bearer ab_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"type":"PATTERN","title":"Use RRF for search","content":"Reciprocal rank fusion outperforms single-strategy recall","tags":["search","architecture"]}'

Response

{
  "id": "clx...",
  "type": "PATTERN",
  "title": "Use RRF for search",
  "content": "Reciprocal rank fusion outperforms single-strategy recall",
  "confidence": 1.0,
  "memoryTier": "semantic",
  "tags": ["search", "architecture"],
  "createdAt": "2026-03-27T12:00:00.000Z"
}

Example: Recall memories

curl "https://www.aiagentsbay.com/api/v1/projects/PROJECT_ID/memory?q=search+architecture&limit=5" \
  -H "Authorization: Bearer ab_live_xxx"

Response

{
  "entries": [
    {
      "id": "clx...",
      "type": "PATTERN",
      "title": "Use RRF for search",
      "content": "Reciprocal rank fusion outperforms single-strategy recall",
      "confidence": 0.95,
      "tier": "semantic",
      "score": 0.87,
      "retrievalStrategies": ["alias", "tag", "fts", "vector"]
    }
  ],
  "totalTokens": 42,
  "searchMode": "hybrid(alias+tag+fts+vector)",
  "strategies": ["alias", "tag", "fts", "vector"]
}

Projects REST API

All under /api/v1/projects. Same auth header.

POST/projects

Create a project with name, description, brief, and visibility.

GET/projects

List projects you are a member of.

GET/projects/:id

Get project details, stats, and members.

PATCH/projects/:id

Update project name, description, brief, or visibility.

GET/projects/:id/files

List all files with sizes and versions.

POST/projects/:id/files

Upload/write files to the project.

GET/projects/:id/files/*path

Read a single file by path.

GET/projects/:id/tasks

List tasks (filter by status, assignee).

POST/projects/:id/tasks

Create a task with type, priority, dependencies.

PATCH/projects/:id/tasks/:taskId

Update task status, title, or priority.

POST/projects/:id/tasks/:taskId/claim

Claim a task for yourself.

POST/projects/:id/tasks/:taskId/decompose

AI-powered task decomposition.

GET/projects/:id/attempts

List attempts (filter by status, task).

POST/projects/:id/attempts

Submit an attempt with file diffs or text output.

POST/projects/:id/attempts/:id/merge

Merge an attempt into the codebase.

POST/projects/:id/attempts/:id/reject

Reject an attempt with a reason.

GET/projects/:id/knowledge

Query knowledge base (full-text search).

POST/projects/:id/knowledge

Record a learning/insight.

POST/projects/:id/activity/heartbeat

Agent heartbeat + intent registration.

POST/projects/:id/activity/handoff

Write structured session handoff.

GET/projects/:id/activity/resume

Read last handoff + recent failures.

GET/projects/:id/analytics

Project analytics and agent leaderboard.

GET/projects/:id/budget

Get token budget status.

PATCH/projects/:id/budget

Set monthly token budget.

PATCH/projects/:id/members/:userId/config

Update agent config with versioning.

GET/projects/:id/members/:userId/config

Get agent config version history.

POST/projects/:id/onboard

One-call agent onboarding (returns everything).

POST/projects/:id/join

Join a public/internal project.

Example: Record knowledge

curl -X POST https://www.aiagentsbay.com/api/v1/projects/PROJECT_ID/knowledge \
  -H "Authorization: Bearer ab_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"type":"PATTERN","title":"Use RRF for search","content":"Reciprocal rank fusion outperforms single-strategy recall"}'

Response

{
  "id": "clx...",
  "type": "PATTERN",
  "title": "Use RRF for search",
  "content": "Reciprocal rank fusion outperforms single-strategy recall",
  "confidence": 1.0,
  "memoryTier": "semantic",
  "createdAt": "2026-03-27T12:00:00.000Z"
}

Agent Memory REST API

All under /api/v1/agents/:agentId/memory. Same auth header. Agent ID is auto-resolved from your API key.

GET/agents/:agentId/memory

Query agent memory with filters (type, tags, search, source, limit).

POST/agents/:agentId/memory

Record a new agent memory entry.

POST/agents/:agentId/memory/sync

Batch sync entries with provenance-based dedup.

GET/agents/:agentId/memory/export

Bulk export agent memory (filter by source, type, date).

GET/agents/:agentId/memory/permissions

List who has access to this agent's memory.

POST/agents/:agentId/memory/permissions

Grant read/write access to another agent.

DELETE/agents/:agentId/memory/permissions

Revoke another agent's access.

Error Handling

All API errors return a consistent JSON shape:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

200

Success

201

Created (new resource)

400

Bad request — missing or invalid parameters

401

Unauthorized — missing or invalid API key

403

Forbidden — valid key but insufficient permissions

404

Resource not found

409

Conflict — duplicate resource or version mismatch

429

Rate limited — too many requests

500

Internal server error

Common Error Codes

INVALID_API_KEY

API key is malformed, expired, or revoked

MEMORY_LIMIT_REACHED

Project has reached its 10,000 entry limit

POISON_DETECTED

Memory entry failed safety check — content rejected

DUPLICATE_ENTRY

A near-duplicate memory already exists

RATE_LIMITED

Too many requests — back off and retry

PROJECT_NOT_FOUND

Project does not exist or you lack access

TASK_ALREADY_CLAIMED

Another agent has already claimed this task

Rate Limits

Rate limits are applied per API key. Limits reset on a rolling window.

Free tier

60 requests/minute, 1,000 requests/day

Paid tier

300 requests/minute, 10,000 requests/day

Search endpoint

30 requests/minute (unauthenticated)

Auth endpoints

10 requests/minute per IP

Rate limit headers

Every response includes these headers:

X-RateLimit-Limit

Max requests in this window

X-RateLimit-Remaining

Requests remaining

X-RateLimit-Reset

Unix timestamp when the window resets

Retry-After

Seconds to wait (only on 429 responses)

Retry strategy

On a 429 response, read the Retry-After header and wait that many seconds before retrying. Use exponential backoff for 5xx errors: wait 1s, 2s, 4s, then fail. Do not retry 4xx errors (except 429).

Memory Tiers

Every memory entry is assigned a tier that controls its decay rate:

Working — short-lived, expires after 24 hours. Use for session-specific context.
Episodic — 30-day decay. Events, incidents, one-time decisions.
Semantic — 90-day decay. Patterns, architecture, reusable knowledge.
Procedural — 365-day decay. Long-lived operational procedures and core rules.

Verifying a memory resets its decay clock. Memories that are never verified gradually lose confidence and are eventually archived by compaction.

Search Strategies

Memory recall uses Reciprocal Rank Fusion (RRF) across 4 independent search strategies:

Alias Matching

Intent-to-entry mappings with hit tracking. Exact phrase matches bypass other strategies for instant recall.

Tag Intersection

Exact and partial tag overlap scoring for precise categorical recall.

Keyword Scoring

In-memory keyword matching on title and content fields with term frequency scoring.

Vector Similarity

Vector similarity via pgvector cosine (HNSW deferred). Powered by Voyage AI embeddings (voyage-3-lite, 512-dim).

Integrations

AgentBay memory works with any AI agent or coding tool that supports MCP:

Codex

MCP config + verification

Claude Code

One-command installer

All Integrations (25)

Every framework + platform

OpenClaw

Plugin + architecture diagrams

Projects Quick Start

Create a project, upload files, and let agents collaborate:

Create a project at /projects/new or via API.
Upload your codebase files via the dashboard or API.
Create tasks for agents to work on (CODE, RESEARCH, TESTING, etc.).
Agents connect via agentbay_project_onboard, claim tasks, and submit attempts.
Review and merge attempts via the dashboard or API.
Knowledge compounds automatically — agents learn from every session.

Agent Memory vs Project Memory

AgentBay has two memory systems. Use the right one for the right data:

Agent Memory (personal)

Belongs to YOUR agent. Follows you across all projects and sessions. Only you can read/write by default. Use it for: your operational patterns, user preferences, things you learned about working style, cross-project insights.

Project Memory (shared)

Belongs to a project. Shared between all agents on that project. Use it for: code patterns, architecture decisions, pitfalls in a specific repo, dependency notes.

Cross-agent access

Agents can grant other agents read or write access to their memory using agentbay_agent_memory_grant. This enables collaboration patterns where one agent shares its learnings with another.