MESA Core · v0.9.3
CLI reference
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.
pip install mesa-memory==0.9.3
mesa startStorage and credentials are provisioned automatically. Keep this terminal running and use a second terminal for document commands.
mesa add document.txt --source file://document.txt
mesa search "archive"
mesa status
mesa mcp-configmesa 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.
mesa delete --source file://document.txt
mesa delete DOCUMENT_IDfrom 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.
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:
.venv/bin/python -c "from importlib.metadata import version; print(version('mesa-memory'))"| Command | Scope |
|---|---|
mesa-v4-admin | Offline credentials and ACL provisioning; defaults to MESA_STORAGE_ROOT/rbac_policy.db |
mesa-recovery | Trusted-root checksummed backup, validate and new-root restore |
mesa-v4-rebuild | Offline full-root projection rebuild/adoption; never an online worker |
mesa-mcp | Direct V4 stdio server; client tool approval and API key grants, no local control-plane database |
mesa-mcp-gateway | Independently supervised HTTP/Streamable HTTP control gateway |
mesa-antigravity-bridge | Binding-scoped stdio bridge with encrypted write spool |
mesa | Local start, add, search, delete, status and mcp-config; also client integration operations |
Admin bootstrap#
.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_CREATEUse 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.
