ensue-cli

CLI for Ensue Memory - a distributed memory network for AI agents built on MCP, enabling persistent, shared context across conversations and applications.

Installation

pip install ensue-cli

Usage

Set your authentication token:

export ENSUE_TOKEN=your-token

List available commands:

ensue --help

Every memory-server tool is also available as a command of its own name, loaded dynamically from the server (ensue create_memory --help).

Reading and writing memory: ensue mem

Six verbs cover everyday use, by people and by agents:

ensue mem get    <key>...              # print a record's value (raw, pipeable)
ensue mem ls     <prefix>              # keys under a prefix, newest first
ensue mem search "<question>"          # semantic search, best match first
ensue mem put    <key> [file|-]        # create or replace one record
ensue mem new    <prefix> [file|-]     # write under a fresh, time-ordered key
ensue mem rm     <key>... --yes        # delete records

ensue mem put LOOP-acme-meta/measure measure.json
KEY=$(ensue mem new LOOP-acme-runs/ run.json)
ensue mem ls LOOP-acme-runs/ --limit 20
ensue mem get LOOP-acme-best | jq .headline
echo '{"text": "baseline measured"}' | ensue mem new LOOP-acme-conversation/agent/

• Values come from a file, from stdin (-, or piped), or from --value. A .json file must parse, and empty values are refused.
• Prefixes are literal: _ and % in a key are not wildcards.
• put and new index the value for search unless you pass --no-embed, and derive the record's one-line description from its description, title or text field (or first line) unless you pass -d.
• Every verb takes --json. ensue mem <verb> --help has the details.

A campaign's code: ensue repo

Each campaign has a git repository hosted by Ensue. --project takes the campaign's id or slug (ensue list_available_projects lists them):

ensue repo clone  --project <slug> [dir]           # clone it, authenticated with ENSUE_TOKEN
ensue repo import --project <slug> <git-url>       # seed an empty one from a repository, once
ensue repo url    --project <slug>                 # print the clone URL (no credentials)

The key is written to ~/.ensue/git-credentials (mode 0600) for git to read; it is never put in a URL or on the command line.

Running an autoresearch agent: ensue agent

ensue agent is the protocol an autoresearch agent follows inside one campaign (ENSUE_PREFIX, ENSUE_REPO_DIR). Every rule is enforced in code, and every refusal says why and what to do instead:

ensue agent status                     # phase, measure, best, editable files, messages
ensue agent steer                      # read the person's new messages
ensue agent files | check [--fix]      # what may be edited; current changes, allowed or locked
ensue agent measure measure.json       # propose a measure (runs the baseline itself)
ensue agent queue                      # ideas queued for the agent, not tried yet, theirs first
ensue agent idea idea.json             # record an idea of its own before trying it
ensue agent run --idea KEY -m "..."    # commit, score, keep or revert, record the run
ensue agent note "..." -e RUN_KEY      # record a lesson, citing runs
ensue agent say "..." | doing "..."    # message the person; one-line status

• Only files the person lists in agent/editable may change (none by default). The measure's eval_files are always locked. run restores locked files, records the run as failed, and names them.
• Scores are measured by the tool (the agreed command and regex), never reported by the agent. Eval side effects are discarded after each scoring.
• measure, idea and run refuse while the person has unread messages, run waits for an accepted measure, and Stop exits every working verb with code 3.
• The person's queued ideas (a /try, or one added in the chat) come first: idea refuses while one is untried. queue lists them, then onboarding's proposals, and run --idea KEY moves each shared-schema hypothesis (deepearth.hypothesis/1) to running, then completed or rejected.

Configuration

• ENSUE_TOKEN (required): Your Ensue API token
• ENSUE_URL (optional): API endpoint (defaults to https://api.ensue-network.ai/)
• ENSUE_PREFIX (optional): every key ensue mem reads or writes must start with this
• ENSUE_WRITABLE (optional): comma-separated patterns, relative to ENSUE_PREFIX, that ensue mem writes must match, e.g. runs/*,meta/measure. Use both to fence an agent into its own part of memory. This is a guard rail; the key's server-side grants are the security boundary.