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:

| Memory Type | What it stores | Key tools | |-------------|----------------|-----------| | Episodic | Time-stamped events, observations, conversations | memory_store_episode, memory_search_episodes | | Entity | Named entities with typed properties | memory_store_entity, memory_get_entity | | Graph | Knowledge graph triples, traversal, pathfinding | memory_traverse_graph, memory_find_path | | Procedural | Goal-directed skill sequences with outcome tracking | memory_store_procedure, memory_match_procedure | | Working | Ephemeral key-value scratchpad (TTL-aware) | memory_set_working, memory_get_working | | Shared | Multi-agent shared knowledge spaces | memory_create_shared_space, memory_shared_query | | Pheromone | Stigmergic trails on memory paths | memory_deposit_pheromone, memory_get_pheromone |

Key differentiators:

• 🚀 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):

``bash 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 apikey) and the limit is **monthlyoplimit** (not opsper_month`).

• Python 3.9+ with requests:

``bash 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](#api-reference).

All 35 MCP Tools

Episodic Memory (5 tools)

| Tool | Description | |------|-------------| | memory_store_episode | Store a time-stamped event or observation | | memory_get_episodes | Retrieve episodes by agent, with pagination | | memory_search_episodes | Natural-language search — hybrid retrieval (TF-IDF ∪ dense embeddings, RRF-fused) | | memory_search_timeline | Search within a specific time window | | memory_consolidate_episodes | Merge related episodes into a summary |

Entity Memory (5 tools)

| Tool | Description | |------|-------------| | memory_store_entity | Store a named entity with typed properties | | memory_get_entity | Retrieve entity by name or ID | | memory_list_entities | List entities with prefix/type filter | | memory_store_relation | Store a typed relationship between two entities (by entity ID) | | memory_get_relations | Get all relations for an entity |

Graph Operations (5 tools)

| Tool | Description | |------|-------------| | memory_query_graph | Keyword graph query over stored triples | | memory_semantic_search | Vector similarity search across memory types | | memory_get_neighbors | Get direct neighbors of a graph node | | memory_find_path | A* pathfinding between concepts (pheromone/shortest/semantic) — Builder+ tier | | memory_traverse_graph | BFS outward from a start node (free on every tier) |

Graph Direct (3 tools)

| Tool | Description | |------|-------------| | memory_graph_add_triple | Add a (subject, predicate, object) triple directly | | memory_graph_neighbors | Get low-level graph neighbors of a node | | memory_graph_shortest_path | Shortest path between two nodes |

Procedural Memory (4 tools)

| Tool | Description | |------|-------------| | memory_store_procedure | Store a named, goal-directed step sequence | | memory_get_procedure | Retrieve procedure with success/fail stats | | memory_match_procedure | Find the best procedure for a task description | | memory_update_procedure | Update steps or record execution outcome |

Working Memory (4 tools)

| Tool | Description | |------|-------------| | memory_set_working | Set key-value with optional TTL ( 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 ), not just an API key.

Episodic Memory

| Tool | Parameter | Type | Req | Default | Description | |------|-----------|------|:---:|---------|-------------| | memory_store_episode | content | string | ✅ | — | Episode text content | | | metadata | object | — | — | Structured metadata (chunk provenance merged in when content is split) | | | valid_at | string | — | now | Validity timestamp (RFC3339) | | | chunk | boolean | — | auto | Force (true) / disable (false) chunking; auto = chunk only when content > chunk_threshold | | | chunk_threshold | integer | — | 6000 | Auto-chunk content longer than this many chars | | | chunk_size | integer | — | 2800 | Target chunk size (chars) | | | chunk_overlap | integer | — | 450 | Overlap between consecutive chunks (chars) | | memory_get_episodes | limit | integer | — | 10 | Max episodes to return (most recent first) | | memory_search_episodes | query | string | ✅ | — | Search text — full detail in the [table above](#memorysearchepisodes-parameters) | | | limit | integer | — | 12 | Max evidence items to return | | | use_hybrid | boolean | — | server default (ON in prod) | Fuse TF-IDF ∪ dense embeddings (RRF) | | | use_pheromone | boolean | — | server default (OFF in prod) | Re-rank by pheromone weight | | | max_content_chars | integer | — | no trim | Trim each result's content to N chars | | memory_search_timeline | start_time | string | ✅ | — | Window start (RFC3339) | | | end_time | string | ✅ | — | Window end (RFC3339) | | memory_consolidate_episodes | before_time | string | — | 7 days ago | Consolidate episodes older than this (RFC3339); those with pheromone weight † 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)

| Tool | Parameter | Type | Req | Default | Description | |------|-----------|------|:---:|---------|-------------| | memory_graph_add_triple | subject | string | ✅ | — | Subject node label | | | predicate | string | ✅ | — | Predicate / edge label | | | object | string | ✅ | — | Object node label | | memory_graph_neighbors | node | string | ✅ | — | Starting node label | | | depth | integer | — | 1 | Hop depth (1–5; capped at 5) | | | direction | string "outgoing"\|"incoming"\|"both" | — | "outgoing" | Edge direction | | memory_graph_shortest_path | from | string | ✅ | — | Source node label | | | to | string | ✅ | — | Target node label | | | undirected | boolean | — | false | Traverse edges in both directions |

Procedural Memory

| Tool | Parameter | Type | Req | Default | Description | |------|-----------|------|:---:|---------|-------------| | memory_store_procedure | name | string | ✅ | — | Procedure name | | | description | string | — | — | Description | | | steps | array<string\|object> | — | [] | Ordered steps: plain strings, or objects {action, tool?, expected_output?} | | | tags | array<string> | — | [] | Tags | | | preconditions | array<string> | — | [] | Preconditions | | memory_get_procedure | procedure_id | string | ✅ | — | Procedure UUID — one of procedure_id / name required | | | name | string | ✅ | — | Procedure name (alternative to procedure_id) | | memory_match_procedure | task | string | ✅ | — | Task description to match against stored procedures | | | limit | integer | — | 5 | Max procedures to return | | memory_update_procedure | procedure_id | string | ✅ | — | Procedure UUID to update — one of procedure_id / name required | | | name | string | ✅ | — | Procedure name (alternative to procedure_id) | | | steps | array<string\|object> | ✅ | — | New ordered steps (replaces old; creates a new version) | | | reason | string | — | — | Reason for the update |

Working Memory

| Tool | Parameter | Type | Req | Default | Description | |------|-----------|------|:---:|---------|-------------| | memory_set_working | key | string | ✅ | — | Working memory key | | | content | string | ✅ | — | Value to store (value accepted as a legacy alias; non-strings are JSON-encoded) | | | ttl_seconds | integer | — | none (no expiry) | Time-to-live in seconds | | | session_id | string | — | — | Optional session scope | | memory_get_working | key | string | ✅ | — | Key to fetch (returns found:false if absent/expired) | | memory_list_working | (none) | — | — | — | Lists all live working-memory items | | memory_clear_working | key | string | — | — | Key to delete; omit to clear ALL working memory |

Pheromone

| Tool | Parameter | Type | Req | Default | Description | |------|-----------|------|:---:|---------|-------------| | memory_deposit_pheromone | node_id | string | ✅ | — | Episode UUID or entity name/ID to reinforce | | | strength | number | — | 1.0 | Pheromone deposit strength | | memory_get_pheromone | node_id | string | ✅ | — | Episode UUID or entity name/ID to query |

Shared Memory Spaces (JWT auth required)

| Tool | Parameter | Type | Req | Default | Description | |------|-----------|------|:---:|---------|-------------| | memory_create_shared_space | name | string | ✅ | — | Space name (1–128 characters) | | memory_join_shared_space | space_id | string | ✅ | — | Space ID to join (JWT must grant access to it) | | | role | string "owner"\|"writer"\|"reader" | — | "writer" | Requested role | | memory_shared_store_entity | space_id | string | ✅ | — | Space ID (requires writer/owner role) | | | name | string | ✅ | — | Entity name | | | entity_type | string | — | "thing" | Entity type | | | description | string | — | — | Description | | memory_shared_query | space_id | string | ✅ | — | Space ID (requires reader/writ

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fetchai
• Source: fetchai/agentverse-skills
• License: Apache-2.0
• Homepage: https://agentverse.ai

Install and usage instructions live in the source repository linked above.