Agentverse Memory

Agentverse Memory

Overview

Give any AI agent persistent, graph-native memory. Agentverse Memory is a managed MCP service that exposes 35 JSON-RPC 2.0 tools for:

Key differentiators:

• 🚀 <5ms writes, $0 ingest — zero LLM inference at write time. Embeddings are computed lazily on the read path and cached per agent, so ingestion never pays an LLM/embedding bill. This is the core cost moat.
• 🌐 Graph memory on every tier — including free. Knowledge triples, BFS graph traversal, and all 4 memory types are available on the free Explorer tier (most vector-only free tiers don't include graph at all).
• 🔀 Hybrid retrieval by default — lexical (TF-IDF) and dense (text-embedding-3-small) candidate sets fused via Reciprocal Rank Fusion (RRF, k=60). Live default-on in production.
• 🐜 Pheromone-guided retrieval (opt-in) — stigmergic trails that boost frequently-recalled memories. Best for warm-cache / repeated-access and multi-agent shared workloads; off by default for single-pass queries.
• 🔗 MCP-native — 35 tools over JSON-RPC; works with Claude, Cursor, Codex, Copilot, Gemini CLI.

Positioning (honest): Agentverse Memory competes on total cost of ownership ($0 write-time inference), graph at every tier, native MCP, and multi-agent pheromone transfer — not on a claim of higher raw retrieval accuracy than other systems. Keep the headline on cost and capabilities.

When to Use

• Agent needs to remember things across conversations/sessions
• Agent needs to build a knowledge graph from interactions
• Agent needs to find connections between concepts (graph traversal, shortest path)
• Agent needs to share knowledge with other agents (shared spaces)
• Agent needs a scratchpad for active task state (working memory)
• Agent needs to recall what it knew at a specific time (temporal queries)
• Agent needs to reuse proven workflows across tasks (procedural memory)

When NOT to Use

• You want in-process (local) memory → use Python dict / Redis directly
• You only need simple key-value storage with no graph → use memory_set_working
• You want vector similarity search only (no graph) → any vector DB works

Prerequisites

• AM_API_KEY environment variable set (prefix: am_)
  • Get a free key (real response shape shown below):

    curl -X POST https://am-server-jbneh74b5q-uc.a.run.app/v1/keys \
      -H "Content-Type: application/json" \
      -d '{"agent_id":"my-agent","tier":"explorer"}'
    # → {"agent_id":"my-agent","key":"am_xxxxxxxx","key_id":"...",
    #    "monthly_op_limit":50000,"tier":"explorer","warning":"Store this key securely..."}
    

    The field is key (not api_key) and the limit is monthly_op_limit (not ops_per_month).
• Python 3.9+ with requests:

  pip install requests
  

Onboarding paths that work today:

1. The bundled scripts/memory_client.py CLI (recommended — covers the common operations).
2. Raw curl / MCP calls to …/mcp (works from any language).

A first-party Python / TypeScript SDK is coming soon (pending package publish). The PyPI/npm packages are not yet live, so don't rely on pip install agentverse-memory / npm install @fetchai/agentverse-memory yet — use the bundled script or raw MCP for now.

Quick Steps

1. Get a free API key

curl -X POST https://am-server-jbneh74b5q-uc.a.run.app/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "my-agent", "tier": "explorer"}'
# → {"agent_id":"my-agent","key":"am_xxxxxxxxxxxxxxxx","key_id":"...",
#    "monthly_op_limit": 50000, "tier": "explorer", "warning": "..."}

# Export the value of the "key" field:
export AM_API_KEY="am_xxxxxxxxxxxxxxxx"

2. Check service health

curl https://am-server-jbneh74b5q-uc.a.run.app/health
# → {"service":"am-server","status":"ok","version":"0.1.0"}

3. Store an episodic memory

python3 skills/agentverse-memory/scripts/memory_client.py store-episode \
  --agent-id "my-agent" \
  --content "User Alice asked about quantum computing and preferred simple analogies"

4. Query episodic memories (hybrid retrieval)

python3 skills/agentverse-memory/scripts/memory_client.py query-episodes \
  --agent-id "my-agent" \
  --query "quantum computing preferences" \
  --limit 5
# Result includes "retrieval":"hybrid" (TF-IDF ∪ dense, RRF-fused).
# Add --no-hybrid to force lexical-only, or --use-pheromone for warm-cache re-ranking.

5. Store a knowledge graph fact

python3 skills/agentverse-memory/scripts/memory_client.py store-fact \
  --agent-id "my-agent" \
  --subject "Alice" \
  --predicate "prefers_explanation_style" \
  --object "simple analogies"

6. Find graph path between concepts (Builder+ tier)

python3 skills/agentverse-memory/scripts/memory_client.py find-path \
  --agent-id "my-agent" \
  --start "Alice" \
  --end "quantum computing"
# A* pathfinding requires the Builder tier or above. On the free Explorer tier
# use traverse-graph (BFS), which is available everywhere.

7. Working memory scratchpad

python3 skills/agentverse-memory/scripts/memory_client.py set-working \
  --agent-id "my-agent" \
  --key "current_task" \
  --value '{"task": "write report", "status": "in_progress"}' \
  --ttl 3600

8. Direct MCP call (curl)

curl -X POST https://am-server-jbneh74b5q-uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AM_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "memory_store_episode",
      "arguments": {
        "agent_id": "my-agent",
        "content": "User prefers dark mode in all interfaces",
        "source": "user"
      }
    }
  }'

⚠️ Onboarding gotcha: JSON-RPC must be POSTed to the /mcp path, not the base URL. POSTing to the base URL returns an actionable error (it will not silently succeed). Always set your endpoint to …/mcp.

8b. Bash CLI (mem) — optional, shell-first workflows

For shell-first workflows there is a small mem CLI (built around curl + jq) distributed with the Agentverse Memory service. It wraps the same /mcp endpoint:

export AM_BASE_URL="https://am-server-jbneh74b5q-uc.a.run.app"   # MEM_URL is derived as $AM_BASE_URL/mcp
export AM_API_KEY="am_xxxxxxxxxxxxxxxx"

mem doctor                                            # validate the onboarding chain
mem episode "User prefers dark mode" '{"tags":["pref"]}'
mem search "dark mode"
mem stats

mem doctor checks env → /mcp → auth → a metadata round-trip → the usage meter and prints a PASS/FAIL checklist. If you don't have the mem CLI installed, the bundled scripts/memory_client.py (above) covers the same operations and works out of the box with only requests.

9. Python / TypeScript SDK (coming soon)

A first-party SDK is in progress:

# NOT YET PUBLISHED — do not use yet:
#   pip install agentverse-memory          (PyPI package not live)
#   npm install @fetchai/agentverse-memory (npm package not live)

Until the packages are published, use scripts/memory_client.py or call the /mcp endpoint directly (any language with an HTTP client works — it's plain JSON-RPC 2.0). Track SDK status at the docs site linked under API Reference.

All 35 MCP Tools

Episodic Memory (5 tools)

Entity Memory (5 tools)

Graph Operations (5 tools)

Graph Direct (3 tools)

Procedural Memory (4 tools)

Working Memory (4 tools)

Pheromone (2 tools)

Shared Memory Spaces (5 tools)

Utility (2 tools)

memory_search_episodes parameters

The result reports the retrieval mode used as "retrieval": "hybrid" or "retrieval": "tfidf".

Tool Parameter Reference (all 35 tools)

Complete parameters for every tool, grouped by memory type. Each tool's arguments go inside the JSON-RPC params.arguments object (see Direct MCP call). The five tools that publish a live inputSchema via tools/list (memory_store_episode, memory_search_episodes, memory_set_working, memory_graph_neighbors, memory_graph_shortest_path) match the tables below; this section documents the remaining tools that don't yet advertise a schema.

Conventions

• agent_id is not a tool argument. Your identity — and which memory palace you read/write — is derived from the AM_API_KEY you authenticate with. (The --agent-id flag in memory_client.py is a client-side convenience; the server ignores any agent_id passed in arguments.)
• ✅ = required · — = optional / not applicable · timestamps are RFC3339 strings (use a Z suffix for UTC).
• Shared-space tools additionally require JWT auth (Authorization: Bearer <jwt>), not just an API key.

Episodic Memory

Entity Memory

Graph Operations

† memory_find_path (A* pathfinding) is tier-gated: lower tiers receive an in-band -32002 forbidden error. Use memory_traverse_graph (BFS), which is available on every tier, where A* isn't enabled.

Graph Direct (low-level triple store)

Procedural Memory

Working Memory

Pheromone

Shared Memory Spaces (JWT auth required)

Utility

Response Shapes (all 35 tools)

The top-level keys in each tool's success payload (the structuredContent object — see Tool call response). All shapes are verified against the live server. Failures instead return isError:true + structuredContent.error{code,type,message} (see Edge Cases).

Episodic

Entity

Graph Operations

Graph Direct

Procedural

Working

Pheromone

Shared Spaces (JWT auth)

Utility

MCP Protocol Details

Endpoint: POST https://am-server-jbneh74b5q-uc.a.run.app/mcp Auth: X-API-Key: am_xxxxxxxxxxxxxxxx

Protocol version negotiation — the server implements the current MCP spec and negotiates the protocol version on initialize. It accepts versions up to the release candidate 2026-07-28 and defaults to 2025-11-25 when the client omits or requests an unknown version (it returns a supported version rather than erroring):

{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": { "protocolVersion": "2026-07-28", "capabilities": {},
              "clientInfo": { "name": "my-client", "version": "1.0" } } }

Tool call request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_store_episode",
    "arguments": { "agent_id": "...", "content": "..." }
  }
}

Tool call response — results carry both a human-readable content block and a typed structuredContent payload, plus an isError flag (MCP-spec result shape):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{\"stored\":true,\"id\":\"5d9d...\"}" }],
    "isError": false,
    "structuredContent": { "stored": true, "id": "5d9d...", "ids": ["5d9d..."], "chunks": 1 }
  }
}

Errors are reported in-band — a failing tool call returns isError: true with a structured error in structuredContent.error (it is not a top-level JSON-RPC error, so it won't trip strict transports):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "validation error on 'task': required field missing or invalid" }],
    "isError": true,
    "structuredContent": { "error": { "code": -32004, "type": "validation_error",
                                       "message": "validation error on 'task': ..." } }
  }
}

(The only protocol-level JSON-RPC error is the auth gate — a missing/invalid API key.)

Typed outputs: five read tools declare an outputSchema so clients can validate results without parsing text — memory_get_episodes, memory_search_episodes, memory_list_entities, memory_semantic_search, memory_get_stats.

Tools list: POST /mcp with {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

Shared Spaces & JWT Authentication

The five memory_*_shared_* / memory_create_shared_space / memory_join_shared_space tools are multi-agent and need a different credential than the rest of the API.

• Single-agent tools (30): authenticate with your API key (X-API-Key: am_… or Authorization: Bearer am_…). Fully self-serve via POST /v1/keys.

• Shared-space tools (5): require a JWT (Authorization: Bearer <jwt>). The server gates access in two steps — tier first, then JWT:

  • Explorer (free) tier — the tier gate fires first: any shared-space tool call returns an in-band -32002 forbidden ("forbidden: tier 'explorer' cannot access 'builder' feature"). No shared spaces on the free tier; upgrade to Builder ($19/mo).

  • Builder+ tier without a JWT — the JWT auth gate fires next: returns an in-band -32001 unauthorized:

    { "isError": true,
      "structuredContent": { "error": { "code": -32001, "type": "unauthorized",
        "message": "unauthorized: Shared space operations require JWT authentication. Use 'Authorization: Bearer <jwt>' with a valid JWT token." } } }
    

How to obtain a JWT

Builder+ tiers can now self-serve a JWT via POST /v1/space-token! Send your API key and the server returns a short-lived HS256 token scoped to the spaces you own or belong to. The spaces[] claim is computed server-side from your membership — you can't request arbitrary spaces. The JWT expires after 1 hour (default, configurable 60–86400s) and can be refreshed anytime.

curl -s -X POST https://am-server-jbneh74b5q-uc.a.run.app/v1/space-token \
  -H "X-API-Key: am_YOUR_BUILDER_KEY"
# → { "token": "eyJ...", "token_type": "Bearer",
#     "expires_at": "2026-06-30T12:26:00Z", "expires_in": 3600,
#     "tier": "builder", "agent_id": "agent-abc123", "spaces": [...],
#     "usage": "Use as Authorization: Bearer <token> with shared-space MCP tools" }

Explorer (free) tier does not include shared spaces. /v1/space-token returns 403 -32002 for Explorer keys. Upgrade to Builder ($19/mo) for up to 3 owned spaces.

The server-generated JWT uses these claims:

Wrong iss/aud/signature, an expired token, or a missing required claim are rejected at the auth gate (jwt_invalid_issuer / jwt_invalid_audience / jwt_invalid_signature / jwt_expired / jwt_missing_claim).

Self-hosted / BYOC: If you run your own am-server, set JWT_SECRET env var to enable JWT auth. Without it, /v1/space-token returns 503 -32007 ("JWT_SECRET is unset"). You'll need to mint tokens yourself using the claim shape above (HS256, with your secret).

Typical multi-agent flow (self-serve)

1. Owner → POST /v1/space-token with Builder+ API key → receives JWT.
2. Owner (JWT) → memory_create_shared_space {name} → returns space_id.
3. Owner → re-mint JWT via POST /v1/space-token (now includes the new space in spaces[]). Bootstrap complete.
4. Collaborators → each gets their own Builder+ key → POST /v1/space-token → JWT scoped to their spaces.
5. Members (JWT) → memory_join_shared_space {space_id, role} → roles: owner > writer > reader.
6. Writers/owners → memory_shared_store_entity {space_id, name, …}; readers+ → memory_shared_query {space_id, query}; any member → memory_list_shared_spaces.

Insufficient role within a space returns an in-band -32002 (forbidden).

Pricing

• All 4 memory types and knowledge-graph triples are available on every tier, including free — that's the core differentiator vs vector-only free tiers.
• Builder adds A* pathfinding + shared spaces; overage billed at $0.005 / 1K ops.
• Pro adds Active Inference + cross-agent queries.
• Enterprise adds SLA, SOC 2, and BYOC (Bring Your Own Cloud).

Get started free: POST /v1/keys with "tier": "explorer".

API Reference

Verified documentation (all live):

• Docs home: https://fetchai.github.io/agentverse-memory/
• Docs index: https://fetchai.github.io/agentverse-memory/docs/
• MCP integration guide: https://fetchai.github.io/agentverse-memory/docs/mcp
• Python SDK docs (SDK publish pending): https://fetchai.github.io/agentverse-memory/docs/python-sdk

How It Works

1. Write path ($0, <5ms): Content → TF-IDF keyword extraction → embedded sled store. No LLM and no embedding inference at write time — ingestion is free and fast.
2. Read path (hybrid): Query → TF-IDF lexical candidates ∪ dense-embedding candidates (text-embedding-3-small, computed lazily on read and cached per agent) → fused via Reciprocal Rank Fusion (RRF, k=60) → optional pheromone re-ranking when use_pheromone:true.
3. Graph: Knowledge triples form an in-memory graph; BFS traversal is available on every tier, A* pathfinding (pheromone/shortest/semantic strategies) on Builder+.
4. Pheromone decay: w(t) = w₀ × exp(-Δt/τ) — lazy computation at query time, no background daemon. Pheromone re-ranking is opt-in (default off) and most valuable for warm-cache / repeated-access and multi-agent shared workloads.
5. Shared spaces: Dedicated storage namespace per space; DID/VC access control for ASI Chain identity.

Cost note: Because embeddings are computed on the read path and cached — never at write time — ingesting a large corpus costs $0 in LLM/embedding fees and writes stay under 5ms. An internal within-harness benchmark (LOCOMO) measured hybrid retrieval lifting answer quality +4.8pp overall / +7.5pp single-hop versus lexical-only, while preserving the zero-LLM-write property. (Internal, within-harness measurement — not a cross-vendor accuracy claim.)

Edge Cases

• Rate limits: 429 response — check X-RateLimit-Reset header and retry after reset
• No / bad API key: 401 response — set AM_API_KEY and ensure it starts with am_
• Tool execution error: returned in-band as isError:true + structuredContent.error{code,type,message} (HTTP 200), e.g. -32004 for argument-validation failures — fix the arguments and retry
• Unknown tool name: top-level JSON-RPC -32601 ("unknown tool") — verify the name matches the 35-tool list (all lowercase, memory_ prefix)
• Tier-gated feature: in-band -32002 ("forbidden: tier ... cannot access ...") — e.g. A* find_path on the free tier; upgrade or use BFS traverse_graph
• Large content: episode content limited to 64KB; triple subject/predicate/object to 1KB each
• Temporal filter: valid_at ISO 8601 string — use Z suffix for UTC

References

• Agentverse Memory Docs
• MCP Integration Guide
• Agentverse Platform