CLI

The AMFS CLI provides commands for inspecting, diffing, and snapshotting memory from the terminal.

Table of Contents

  1. Installation
  2. Initialize a Project
  3. Inspect Memory
    1. List Entries
    2. Read an Entry
    3. Diff Version History
  4. Snapshots
    1. Export
    2. Restore
  5. Custom Config Path
  6. Connecting to AMFS SaaS
    1. Environment Variables
  7. MCP Server

Installation 

pip install amfs-cli

Initialize a Project 

amfs init

Creates amfs.yaml, .amfs/, and updates .gitignore. Run this once per project.

Inspect Memory

List Entries 

# List all entries
amfs inspect list

# List entries for a specific entity
amfs inspect list checkout-service

# Include superseded versions
amfs inspect list checkout-service --superseded

Read an Entry 

amfs inspect read checkout-service retry-pattern

Diff Version History

See how an entry changed across versions:

amfs inspect diff checkout-service retry-pattern

Snapshots

Export

Export all memory to a JSON file:

amfs snapshot export backup.json

Export a single entity:

amfs snapshot export backup.json --entity checkout-service

Include superseded versions:

amfs snapshot export backup.json --superseded

Restore

Restore memory from a snapshot:

amfs snapshot restore backup.json

Restore writes entries into the current adapter. Existing entries with the same keys will get new versions via CoW — nothing is overwritten destructively.

Custom Config Path

All commands accept a -c / --config flag:

amfs inspect list -c /path/to/amfs.yaml

Connecting to AMFS SaaS

When using AMFS as a hosted service (SaaS), CLI commands work against local storage by default. To interact with the SaaS instance, use the HTTP API directly or configure the MCP server with AMFS_HTTP_URL.

Environment Variables 

export AMFS_HTTP_URL="https://amfs-login.sense-lab.ai"
export AMFS_API_KEY="amfs_sk_your_key_here"

With these set, the MCP server and HTTP server automatically route through the authenticated HTTP API. CLI inspection commands (amfs inspect, amfs snapshot) still read from the local adapter — use the Dashboard or REST API for remote inspection.

Never use AMFS_POSTGRES_DSN for external agents in multi-tenant mode. Always use AMFS_HTTP_URL + AMFS_API_KEY.

See the SaaS Connection Guide and Environment Variables for details.

MCP Server

The MCP server has its own executable:

# Start with stdio transport (default)
amfs-mcp-server

# Start with HTTP transport
amfs-mcp-server --transport http

# Custom host, port, and path
amfs-mcp-server --transport http --host 127.0.0.1 --port 9000 --path /amfs

See the MCP Setup guide for full details.