# Ensue

> Shared memory network for AI agents.

## Get an API Key

Go to https://www.ensue-network.ai and create an account to get your API key.

Set it as an environment variable:
```bash
export ENSUE_API_KEY="your_api_key"
```

For the CLI, also set:
```bash
export ENSUE_TOKEN="your_api_key"
pip3 install ensue-cli
```

## Call Tools

All tools are called via JSON-RPC at `https://api.ensue-network.ai/`

```bash
curl -X POST https://api.ensue-network.ai/ \
  -H "Authorization: Bearer $ENSUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "<tool_name>",
      "arguments": { ... }
    },
    "id": 1
  }'
```

## Available Tools

### Memory Operations

**create_memory** - Store 1-100 memories
```json
{
  "name": "create_memory",
  "arguments": {
    "items": [
      {
        "key_name": "my/key",
        "description": "Searchable description",
        "value": "The stored data",
        "embed": true,
        "embed_source": "description"
      }
    ]
  }
}
```

**get_memory** - Retrieve memories by key (batch up to 100)
```json
{
  "name": "get_memory",
  "arguments": {
    "key_names": ["my/key", "another/key"]
  }
}
```

**update_memory** - Modify existing memory values
```json
{
  "name": "update_memory",
  "arguments": {
    "key_name": "my/key",
    "value": "Updated data"
  }
}
```

**delete_memory** - Remove 1-100 memories
```json
{
  "name": "delete_memory",
  "arguments": {
    "key_names": ["my/key"]
  }
}
```

### Search & Discovery

**search_memories** - Semantic similarity search
```json
{
  "name": "search_memories",
  "arguments": {
    "query": "what I'm looking for",
    "limit": 10
  }
}
```
Filters: `within_days`, `created_after`, `created_before`, `updated_after`, `updated_before`

**discover_memories** - Semantic search returning keys and metadata only
```json
{
  "name": "discover_memories",
  "arguments": {
    "query": "explore this topic",
    "limit": 10
  }
}
```

**list_keys** - List memory keys with pagination
```json
{
  "name": "list_keys",
  "arguments": {
    "limit": 10,
    "prefix": "my/%"
  }
}
```
Prefix supports SQL LIKE patterns: `%` wildcard, `_` single char

**list_recent_keys** - Most recently created/updated keys
```json
{
  "name": "list_recent_keys",
  "arguments": {
    "limit": 10,
    "sort_by": "updated"
  }
}
```

### Hypergraph

**build_hypergraph** - Generate semantic graph of relationships
```json
{
  "name": "build_hypergraph",
  "arguments": {
    "query": "find connections about this topic",
    "limit": 50,
    "output_key": "graphs/my-graph"
  }
}
```
Models: `llama-3.3-70b`, `llama-3.1-8b`, `mixtral-8x7b`, `qwen-3-32b`

**build_namespace_hypergraph** - Hypergraph within a namespace
```json
{
  "name": "build_namespace_hypergraph",
  "arguments": {
    "namespace": "projects/web",
    "limit": 50
  }
}
```

### Subscriptions

**subscribe_to_memory** - Get notified on memory changes
```json
{
  "name": "subscribe_to_memory",
  "arguments": {
    "key_name": "my/key"
  }
}
```

**unsubscribe_from_memory** - Stop notifications
```json
{
  "name": "unsubscribe_from_memory",
  "arguments": {
    "key_name": "my/key"
  }
}
```

**list_subscriptions** - Show active subscriptions
```json
{
  "name": "list_subscriptions",
  "arguments": {}
}
```

### Sharing & Permissions

**list_permissions** - View all permissions for current user
```json
{
  "name": "list_permissions",
  "arguments": {}
}
```

**share** - Manage users, groups, and permissions
```json
{
  "name": "share",
  "arguments": {
    "command": "grant",
    "target": { "type": "org" },
    "action": "read",
    "key_pattern": "public/"
  }
}
```

Commands:
- Users: `create_user`, `delete_user`
- Groups: `create_group`, `delete_group`, `add_member`, `remove_member`
- Permissions: `grant`, `revoke`, `list`

Target types: `org`, `user`, `group`

Permission levels: `read`, `write`, `update`, `delete`, `share`

Key patterns use regex with forward-slash namespaces (e.g., `^projects/web/.*`)

## Documentation

https://ensue.dev/docs/