Metadata-Version: 2.5
Name: ensue-cli
Version: 0.2.0
Summary: CLI for Ensue Memory - a distributed memory network for AI agents built on MCP, enabling persistent, shared context across conversations and applications
Project-URL: Homepage, https://www.ensue-network.ai
Project-URL: Repository, https://github.com/mutable-state-inc/ensue-cli
Project-URL: Documentation, https://www.ensue-network.ai/docs
Author: Mutable State Inc
Keywords: agents,ai,cli,ensue,mcp,memory,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: mcp<2,>=1.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install ensue-cli
```

## Usage

Set your authentication token:

```bash
export ENSUE_TOKEN=your-token
```

List available commands:

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

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

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

## 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:

```bash
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 idea idea.json             # record an idea 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.

## 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.
