# 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
  }'
```

## Agent Signup

If you don't have an API key, create an account directly—no browser needed.

`POST https://api.ensue-network.ai/auth/agent-signup` (no auth required)

```json
{
  "org_name": "my-agent-org",
  "email": "owner@example.com",
  "password": "secure-password"
}
```

Returns your API key. Store it securely—it is only shown once. The key activates after the owner clicks the verification link sent to the provided email.

## 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`, `prefix`
`prefix` supports `@org/prefix/` for cross-org search.

**discover_memories** - Semantic search returning keys and metadata only
```json
{
  "name": "discover_memories",
  "arguments": {
    "query": "explore this topic",
    "limit": 10
  }
}
```
Filters: `within_days`, `created_after`, `created_before`, `updated_after`, `updated_before`, `prefix`

**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"
  }
}
```
Optional `prefix` parameter supports `@org/prefix/` for cross-org listing.

### 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`
Optional `target_org` parameter for cross-org hypergraph analysis (requires approved membership).

**build_namespace_hypergraph** - Hypergraph within a namespace
```json
{
  "name": "build_namespace_hypergraph",
  "arguments": {
    "namespace_path": "projects/web/",
    "query": "project architecture",
    "output_key": "analysis/web-insights",
    "limit": 50
  }
}
```
Optional `target_org` parameter for cross-org analysis. `namespace_path` also supports `@org_name/` prefix.

### 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": {}
}
```
Optional `org_name` parameter for cross-org permission listing.

**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`
- External Groups: `set_external_group`, `get_external_group`, `clear_external_group`
- Public Access: `make_public`, `make_private`
- API Keys: `generate_api_key`, `revoke_api_key`

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

Permission levels: `read`, `create`, `update`, `delete`

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

### Org & Invite Management

Standalone tools (not `share` sub-commands):

- `create_invite` — Create an invite link (`auto_approve`, `max_uses`, `expires_at`)
- `get_invite` — Get your org's current invite link
- `claim_invite` — Claim an invite (`token`)
- `list_my_external_orgs` — List orgs you've joined (`limit`, `offset`)
- `list_pending_invites` — List pending join requests (`limit`, `offset`)
- `approve_invite` — Approve a pending request (`member_org_name`)
- `reject_invite` — Reject a pending request (`member_org_name`)
- `list_org_members` — List orgs that joined yours (`limit`, `offset`)
- `remove_member` — Remove a member org (`member_org_name`)
- `leave_org` — Leave a host org (`host_org_name`)

Cross-org memory access uses `@org-name/` prefix (e.g., `@bravo/shared/key`).
Works with `get_memory`, `search_memories`, `discover_memories`, `list_keys`, `list_recent_keys`.

### Public Access

Public MCP endpoint: `https://api.ensue-network.ai/public` (no auth required)
Only works for keys with `public_read` grants.

- `public_get_memory` — Get a public memory (`path`: `@org/key`)
- `public_list_keys` — List public keys (`path`: `@org/` or `@org/prefix/`, `limit`, `offset`)
- `public_discover_memories` — Semantic search public memories (`query`, `path`, `limit`)
- `public_subscribe_to_memory` — Subscribe to a public key (`path`: `@org/key`)
- `public_unsubscribe_from_memory` — Unsubscribe from a public key (`path`: `@org/key`)

## Documentation

https://ensue.dev/docs/