MESA Core · v0.9.3

CLI reference

v0.9.3 source: docs/api-reference.md

This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.

Local single-user commands#

MESA CLI is the command-line interface included with the mesa-memory package. No separate CLI package is needed. Install v0.9.3 and start the local server:

The v0.9.3 package is published on PyPI; the command pins that verified version. See installation and extras.

bash
pip install mesa-memory==0.9.3
mesa start

Storage and credentials are provisioned automatically. Keep this terminal running and use a second terminal for document commands.

bash
mesa add document.txt --source file://document.txt
mesa search "archive"
mesa status
mesa mcp-config

mesa delete DOCUMENT_ID purges a document under the key’s permissions. Purge erases source/extracted text while retaining audit state and hashes; another owning document can retain shared text. mesa mcp-config prints an API key: store its output privately. In Docker, run these commands with docker compose -f docker-compose.v4.yml exec mesa-v4 so they can read volume credentials.

Advanced operator tools#

mesa-v4-admin manages keys, roles and explicit dataset permissions. mesa-v4-rebuild performs offline full-storage-root rebuilds; mesa-mcp-control manages gateway approvals. These are separate from local document commands. Read the version-matched flags and recovery rules below before operating an existing storage root.

Wait for activation and delete by source#

mesa add waits for ACTIVE by default. In the tagged v0.9.3 SDK, Mesa.add defaults to wait=False; pass wait=True explicitly to wait for ACTIVE. Use mesa add document.txt --source file://document.txt --no-wait or Mesa.add(..., wait=False) to return after admission. A terminal chunk failure is reported early with mutation ID, state and error class. RETRY_PENDING is not terminal.

bash
mesa delete --source file://document.txt
mesa delete DOCUMENT_ID
python
from mesa_client import Mesa

with Mesa() as mesa:
    receipt = mesa.add("The archive opens at nine.", source="file://document.txt", wait=True)
    admitted = mesa.add("Another document.", source="file://other.txt", wait=False)
    mesa.delete(source="file://document.txt")

ID-based deletion is retained. Deletion still requires the owning scope and purge permissions.

Verified sources
Source reference for this page

The sections of the upstream file that back this page, translated to English where the original mixes in Turkish. The GitHub link shows the exact original.

CLI commands#

The entry points are declared in pyproject.toml. Run `.venv/bin/<command>

--help` after the locked install. These commands do not have a universal

--version; read package metadata with:

bash
.venv/bin/python -c "from importlib.metadata import version; print(version('mesa-memory'))"
CommandScope
mesa-v4-adminOffline credentials and ACL provisioning; defaults to MESA_STORAGE_ROOT/rbac_policy.db
mesa-recoveryTrusted-root checksummed backup, validate and new-root restore
mesa-v4-rebuildOffline full-root projection rebuild/adoption; never an online worker
mesa-mcpDirect V4 stdio server; client tool approval and API key grants, no local control-plane database
mesa-mcp-gatewayIndependently supervised HTTP/Streamable HTTP control gateway
mesa-antigravity-bridgeBinding-scoped stdio bridge with encrypted write spool
mesaLocal start, add, search, delete, status and mcp-config; also client integration operations

Admin bootstrap#

bash
.venv/bin/mesa-v4-admin --help
.venv/bin/mesa-v4-admin grant-role --principal docs-principal --tenant docs-tenant --role OWNER
.venv/bin/mesa-v4-admin grant-agent --principal docs-principal --agent docs-agent --permission SESSION_CREATE

Use these only against the intended stopped/new policy database. issue-key

prints the credential once; rotate-key --key-id revokes/replaces it.

grant-control assigns ADMIN. grant-dataset-permission explicitly assigns

PURGE/ROLLBACK; role inheritance alone does not give those operations.

Dataset role grants require both --workspace and --dataset. Corresponding

revoke-role/revoke-dataset-permission remove authorization.

Recovery, rebuild and MCP#

Use operations and rebuild for safety,

trusted paths, locking, status, retry/lease, exit codes and retained generations.

Never use arbitrary raw-store cleanup as a CLI substitute.

MCP describes binding credentials, encryption and local

operator approval. mesa operations approve/reject acts on durable operation

IDs with server-side ADMIN authority; it does not bypass gateway policy.

python -m mesa_memory.runtime_entrypoint selects the explicit runtime profile;

there is no mesa serve command. mesa-benchmark belongs to the separate

benchmark project and is not installed by this Core package.