API Reference

Complete API reference for the Ensue memory network.

Public URLs

Service URL
MCP https://api.ensue-network.ai/
Streaming https://events.ensue-network.ai/mcp

Authentication

All API requests require authentication via Bearer token in the Authorization header.

Get Your API Key

  1. Sign in to the Ensue Dashboard
  2. Click Create New Key
  3. Copy the key and store it securely—it won't be shown again

Set Your Environment Variable 

export ENSUE_API_KEY="your-api-key-here"

Request Headers

All requests must include:

Header Value
Authorization Bearer $ENSUE_API_KEY
Content-Type application/json

Base URL 

https://api.ensue-network.ai/

Example Request 

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": "list_keys",
      "arguments": {"limit": 10}
    },
    "id": 1
  }'

Memory Operations

Core operations for creating, reading, updating, and deleting memories.

create_memory

Create one or more memory entries with unique keys. Supports batch operations (1-100 items). Memories can store any type of data and optionally be embedded for semantic search.

Parameters:

Field Type Required Description
items array Yes List of memories to create (1-100 items)

Item fields:

Field Type Required Description
key_name string Yes The unique key name for this memory
description string Yes Description of what this memory contains (used for search)
value string Yes The actual data to store
embed boolean No Generate vector embeddings for semantic search (default: false)
embed_source string No Field to use for embedding: description or value (default: description)
base64 boolean No Whether value is base64 encoded (default: false)

Example:

ensue create_memory --items '[{
  "key_name": "preferences/coding-style",
  "description": "User prefers early returns over nested conditionals",
  "value": "When writing functions, use early returns to handle edge cases first.",
  "embed": true
}]'

Batch Example:

ensue create_memory --items '[
  {"key_name": "project/api/auth", "description": "Auth decision", "value": "Using JWT", "embed": true},
  {"key_name": "project/api/database", "description": "DB choice", "value": "PostgreSQL", "embed": true}
]'

get_memory

Retrieve one or more memories by key names. Supports batch operations (1-100 keys). Returns description, value, size, and timestamps for each key.

Parameters:

Field Type Required Description
key_names string[] Yes List of key names to retrieve (1-100 keys)

Example:

ensue get_memory --key-names '["preferences/coding-style"]'

Batch Example:

ensue get_memory --key-names '["project/api/auth", "project/api/database", "project/api/caching"]'

update_memory

Update the value of an existing memory. Only the value is updated; the description remains unchanged.

Parameters:

Field Type Required Description
key_name string Yes The key name of the memory to update
value string Yes The new value
embed boolean No Regenerate vector embeddings (default: false)
embed_source string No Field to use for embedding: description or value
base64 boolean No Whether value is base64 encoded (default: false)

Example:

ensue update_memory --key-name "preferences/coding-style" --value "Use early returns and guard clauses. Maximum function length: 20 lines." --embed true

delete_memory

Delete one or more memories by key names. Supports batch operations (1-100 keys). Permanently removes memories and their vector embeddings.

Parameters:

Field Type Required Description
key_names string[] Yes List of key names to delete (1-100 keys)

Example:

ensue delete_memory --key-names '["outdated/old-preference"]'

Search & Discovery

Find memories using semantic similarity or browse by key.

search_memories

Search for memories using semantic similarity. Returns results ranked by relevance score with full memory content.

Parameters:

Field Type Required Description
query string Yes Natural language query
limit integer No Maximum results (default: 10, max: 100)
within_days integer No Filter to memories updated within last N days
created_after integer No Filter by Unix timestamp
created_before integer No Filter by Unix timestamp
updated_after integer No Filter by Unix timestamp
updated_before integer No Filter by Unix timestamp

Example:

ensue search_memories --query "authentication decisions" --limit 5

With Time Filter:

ensue search_memories --query "recent bugs" --within-days 7 --limit 10

discover_memories

Discover memory keys using semantic similarity without retrieving values. Returns key names, relevance scores, and metadata. Use this for exploration, then use get_memory to retrieve specific values.

Parameters:

Field Type Required Description
query string Yes Natural language query
limit integer No Maximum results (default: 10, max: 100)
within_days integer No Filter to memories updated within last N days
created_after integer No Filter by Unix timestamp
created_before integer No Filter by Unix timestamp
updated_after integer No Filter by Unix timestamp
updated_before integer No Filter by Unix timestamp

Example:

ensue discover_memories --query "what do I know about caching" --limit 5

list_keys

List memory keys with their metadata (description, size, timestamps). Supports pagination and prefix filtering.

Parameters:

Field Type Required Description
limit integer No Maximum keys to return (default: 100)
offset integer No Offset for pagination (default: 0)
prefix string No Filter by prefix (supports SQL LIKE wildcards: % for any sequence, _ for single char)

Example:

ensue list_keys --limit 20

With Prefix Filter:

ensue list_keys --prefix "projects/web/" --limit 50

list_recent_keys

List the most recently created or updated memory keys, sorted by timestamp (newest first).

Parameters:

Field Type Required Description
limit integer No Maximum keys to return (default: 10, max: 100)
sort_by string No Sort by created or updated

Example:

ensue list_recent_keys --limit 10 --sort-by updated

Hypergraph

Build semantic relationship graphs from your memories.

build_hypergraph

Build a semantic hypergraph from memories matching a search query. The hypergraph identifies semantic clusters and relationships among memories. Returns immediately with a job ID—check the output_key for results.

Parameters:

Field Type Required Description
query string Yes Natural language query to find related memories
limit integer Yes Maximum memories to include (max: 50)
output_key string Yes Key where the hypergraph result will be written
model string No Model for inference: llama-3.3-70b-versatile, llama-3.1-8b-instant, mixtral-8x7b-32768, qwen-3-32b
within_days integer No Filter to memories updated within last N days
created_after integer No Filter by Unix timestamp
created_before integer No Filter by Unix timestamp
updated_after integer No Filter by Unix timestamp
updated_before integer No Filter by Unix timestamp

Example:

ensue build_hypergraph --query "coding mistakes and lessons learned" --limit 30 --output-key "analysis/coding-patterns"

build_namespace_hypergraph

Build a semantic hypergraph from memories within a specific namespace. Only keys starting with the namespace prefix are included.

Parameters:

Field Type Required Description
namespace_path string Yes Namespace prefix (e.g., projects/web/)
query string Yes Query for computing semantic similarity weights
output_key string Yes Key where the hypergraph result will be written
limit integer No Maximum keys to include (default: 50, max: 100)
model string No Model for inference
within_days integer No Filter to memories updated within last N days
created_after integer No Filter by Unix timestamp
created_before integer No Filter by Unix timestamp
updated_after integer No Filter by Unix timestamp
updated_before integer No Filter by Unix timestamp

Example:

ensue build_namespace_hypergraph --namespace-path "sessions/" --query "patterns and recurring issues" --output-key "analysis/session-insights" --within-days 14

Subscriptions

Subscribe to memory changes and receive notifications.

subscribe_to_memory

Subscribe to notifications for changes to a memory key. Receive notifications when the memory is created, updated, or deleted. Subscription duration is limited by your organization's tier (free tier: 3 hours).

Parameters:

Field Type Required Description
key_name string Yes The key name to subscribe to

Example:

ensue subscribe_to_memory --key-name "shared/config"

unsubscribe_from_memory

Unsubscribe from notifications for a memory key.

Parameters:

Field Type Required Description
key_name string Yes The key name to unsubscribe from

Example:

ensue unsubscribe_from_memory --key-name "shared/config"

list_subscriptions

List all active memory subscriptions for the current user. Shows which memory keys you are subscribed to and when each subscription expires.

Parameters: None required.

Example:

ensue list_subscriptions

Sharing & Permissions

Manage access control for memories across users, groups, and organizations.

Access Control Scopes

Ensue supports five permission levels that can be granted to users, groups, or your entire organization:

Scope Description
read View memory content
write Create new memories in the namespace
update Modify existing memory values
delete Remove memories permanently
share Manage permissions for other users

Key Patterns & Namespaces

Permissions are granted on key patterns—regex patterns that match memory keys. Use namespaces to organize and control access:

Pattern Matches Use Case
^public/.* All keys under public/ Org-wide readable content
^alice/.* All keys under alice/ User's private namespace
^projects/web/.* All keys under projects/web/ Project-specific access
^shared/config$ Exact key shared/config Single key access
^team-a/.* All keys under team-a/ Team namespace

Namespace convention: Use forward slashes to create hierarchical namespaces. Grant permissions at the appropriate level:

users/alice/           → Alice's personal memories
projects/acme/         → Acme project team access
org/announcements/     → Organization-wide updates
shared/configs/        → Shared configuration

list_permissions

List all permissions that apply to the current user. Returns permission grants at the organization, group, and user level.

Parameters: None required.

Example:

ensue list_permissions

share

Manage users, groups, and permissions for sharing memory keys. Requires sharing permission.

User Management Commands:

Command Description Example
create_user Create a new user {"command": "create_user", "username": "alice"}
delete_user Delete a user {"command": "delete_user", "username": "alice"}

Group Management Commands:

Command Description Example
create_group Create a new group {"command": "create_group", "group_name": "editors"}
delete_group Delete a group {"command": "delete_group", "group_name": "editors"}
add_member Add user to group {"command": "add_member", "group_name": "editors", "username": "alice"}
remove_member Remove user from group {"command": "remove_member", "group_name": "editors", "username": "alice"}

Permission Management Commands:

Command Description
grant Grant permission to org, user, or group
revoke Revoke a permission grant by ID
list List current permissions

Grant Targets:

Target Type Description Example
org Entire organization {"type": "org"}
user Specific user {"type": "user", "username": "alice"}
group User group {"type": "group", "group_name": "editors"}

Examples:

Grant read access to entire organization:

ensue share --command '{"command": "grant", "target": {"type": "org"}, "action": "read", "key_pattern": "public/"}'

Grant update access to a user:

ensue share --command '{"command": "grant", "target": {"type": "user", "username": "alice"}, "action": "update", "key_pattern": "alice/"}'

Grant delete access to a group:

ensue share --command '{"command": "grant", "target": {"type": "group", "group_name": "editors"}, "action": "delete", "key_pattern": "shared/"}'

Create a group and add members:

ensue share --command '{"command": "create_group", "group_name": "team-a"}'
ensue share --command '{"command": "add_member", "group_name": "team-a", "username": "alice"}'

Revoke a permission:

ensue share --command '{"command": "revoke", "grant_id": "uuid-of-grant"}'

List all permissions:

ensue share --command '{"command": "list"}'

Filter permissions by target type and action:

ensue share --command '{"command": "list", "target_type": "user", "action": "read"}'