# Agentverse Memory

> >

- **Type:** Skill
- **Install:** `agentstack add skill-fetchai-agentverse-skills-agentverse-memory`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fetchai](https://agentstack.voostack.com/s/fetchai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [fetchai](https://github.com/fetchai)
- **Source:** https://github.com/fetchai/agentverse-skills/tree/main/skills/agentverse-memory
- **Website:** https://agentverse.ai

## Install

```sh
agentstack add skill-fetchai-agentverse-skills-agentverse-memory
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 `api_key`) and the limit is **`monthly_op_limit`** (not `ops_per_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
```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_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
```bash
curl https://am-server-jbneh74b5q-uc.a.run.app/health
# → {"service":"am-server","status":"ok","version":"0.1.0"}
```

### 3. Store an episodic memory
```bash
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)
```bash
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
```bash
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)
```bash
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
```bash
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)
```bash
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:

```bash
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:

```text
# 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](#memory_search_episodes-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](https://github.com/fetchai)
- **Source:** [fetchai/agentverse-skills](https://github.com/fetchai/agentverse-skills)
- **License:** Apache-2.0
- **Homepage:** https://agentverse.ai

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fetchai-agentverse-skills-agentverse-memory
- Seller: https://agentstack.voostack.com/s/fetchai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.