CLI Reference

Complete reference for the Aegis Memory command-line interface.

Installation

pip install aegis-memory

Configuration

`aegis init`

Top-level setup wizard with lightweight framework detection (LangChain/CrewAI) and config bootstrap.

aegis init              # Interactive wizard
aegis init -y           # Non-interactive defaults

`aegis new`

Generate starter boilerplate from templates.

aegis new customer-support
aegis new customer-support -o ./examples

`aegis explore`

Interactive memory browser from your terminal.

aegis explore
aegis explore -q "login failures" -k 10

`aegis config init`

Interactive first-run setup.

aegis config init          # Interactive
aegis config init -y       # Use defaults (non-interactive)

`aegis config show`

Display current configuration.

aegis config show

`aegis config set`

Set a configuration value.

aegis config set output.format json
aegis config set profiles.local.api_url http://localhost:8000

Server Status

`aegis status`

Check server health and connection.

aegis status           # Pretty output
aegis status -j        # JSON output
aegis status -q        # Quiet (exit code only)

Exit codes:

0 - Server healthy
1 - Server unhealthy
2 - Connection failed

`aegis stats`

Show namespace statistics.

aegis stats                    # Default namespace
aegis stats -n production      # Specific namespace
aegis stats -a executor        # Filter by agent

Memory Operations

`aegis add`

Add a memory.

aegis add "Memory content"                    # Basic
aegis add "Strategy" -t strategy -s global    # Strategy with global scope
aegis add -f ./insight.txt -t reflection      # From file
echo "Piped" | aegis add                      # From stdin

Options:

Flag	Short	Description
`--agent`	`-a`	Agent ID
`--user`	`-u`	User ID
`--namespace`	`-n`	Namespace
`--scope`	`-s`	Scope: `agent-private`, `agent-shared`, `global`
`--type`	`-t`	Type: `standard`, `strategy`, `reflection`
`--share-with`		Agent IDs to share with
`--metadata`	`-m`	JSON metadata

`aegis query`

Semantic search for memories.

aegis query "search text"                     # Basic search
aegis query "patterns" -t strategy -k 5       # Filter by type
aegis query "task" -x planner,coordinator     # Cross-agent query
aegis query "test" --ids-only                 # IDs only for scripting

Options:

Flag	Short	Description
`--top-k`	`-k`	Number of results (default: 10)
`--min-score`		Minimum similarity score
`--type`	`-t`	Filter by memory type
`--cross-agent`	`-x`	Query across these agents
`--full`		Show full content

`aegis get`

Get a single memory by ID.

aegis get 7f3a8b2c1d4e                        # Pretty output
aegis get 7f3a8b2c1d4e -j                     # JSON output
aegis get 7f3a8b2c1d4e --content-only         # Content only

`aegis update`

Update a memory’s content, metadata, and/or trust level. Changing content re-scans it through the security pipeline and recomputes its embedding (and integrity hash, if enabled). Metadata is merged, not replaced.

aegis update 7f3a8b2c1d4e "Corrected content"     # New content (arg)
aegis update 7f3a8b2c1d4e -f ./fixed.txt          # New content from file
echo "Piped content" | aegis update 7f3a8b2c1d4e  # New content from stdin
aegis update 7f3a8b2c1d4e -m '{"reviewed": true}' # Merge metadata
aegis update 7f3a8b2c1d4e --trust-level privileged

Options:

Flag	Short	Description
`--metadata`	`-m`	JSON metadata to merge
`--trust-level`		New trust level (`untrusted`, `unknown`, `internal`, `privileged`, `system`)
`--file`	`-f`	Read new content from file
`--json`	`-j`	JSON output

At least one of new content, --metadata, or --trust-level must be provided.

`aegis delete`

Delete a memory.

aegis delete 7f3a8b2c1d4e                     # With confirmation
aegis delete 7f3a8b2c1d4e -f                  # Force (no confirmation)

Voting

`aegis vote`

Vote on memory usefulness.

aegis vote <id> helpful                       # Vote helpful
aegis vote <id> harmful -c "Caused bug"       # Vote harmful with context

Options:

Flag	Short	Description
`--voter`	`-v`	Voting agent ID
`--context`	`-c`	Why this vote
`--task`	`-t`	Related task/feature ID

Playbook

`aegis playbook`

Query proven strategies and reflections.

aegis playbook "error handling"               # Search playbook
aegis playbook "API" -t strategy -e 0.5       # Only high-rated strategies

Options:

Flag	Short	Description
`--top-k`	`-k`	Number of results (default: 20)
`--min-effectiveness`	`-e`	Minimum effectiveness score
`--type`	`-t`	`strategy`, `reflection`, or both

Session Progress

`aegis progress create`

Create a new session.

aegis progress create build-api -a executor
aegis progress create feature-x -s "Building feature X" -t 5

`aegis progress update`

Update session progress.

aegis progress update build-api -c auth -c routing
aegis progress update build-api -i api-client
aegis progress update build-api -b "payments:Waiting for API keys"

`aegis progress show`

Show session details.

aegis progress show build-dashboard

Feature Tracking

`aegis features create`

Create a feature.

aegis features create user-auth \
    -d "User authentication with JWT" \
    -c auth \
    -t "Can login" \
    -t "Can logout"

`aegis features verify`

Mark feature as passing.

aegis features verify user-auth --by qa-agent

`aegis features fail`

Mark feature as failed.

aegis features fail 2fa-totp -r "TOTP validation fails"

Data Management

`aegis export`

Export memories to file.

aegis export > backup.jsonl                   # To stdout
aegis export -o backup.jsonl                  # To file
aegis export -n prod -f json -o prod.json     # JSON format

`aegis import`

Import memories from file.

aegis import backup.jsonl                     # Import from file
aegis import backup.jsonl -n staging          # Override namespace
aegis import backup.jsonl --dry-run           # Validate only

Maintenance

`aegis prune`

Archive stale memories via the temporal-decay sweep — soft-deprecates memories whose relevance score falls below the threshold. This is manual, CLI-triggered pruning; OSS has no hosted scheduled policy, so run it on your own schedule (e.g. a cron job).

aegis prune --dry-run                         # Preview count only
aegis prune                                   # Archive in default namespace
aegis prune -n research --threshold 0.2       # Higher cutoff in a namespace

Options:

Flag	Short	Description
`--namespace`	`-n`	Namespace to sweep
`--threshold`	`-t`	Relevance-score cutoff, 0.0–1.0 (default: 0.1)
`--dry-run`		Preview count without modifying rows
`--json`	`-j`	JSON output

Security Analysis

These commands are standalone and server-free — they run offline static analysis and a local scan, and need no running server or API key.

`aegis inspect`

Inspect an agent project for unsafe memory flows. Writes results to aegis-out/ (including findings.sarif for GitHub code scanning). Suppress an accepted sink with an inline # aegis: ignore comment.

aegis inspect .                               # Inspect current directory
aegis inspect ./agent --framework langgraph   # Force a sink adapter
aegis inspect . --ci --max-risk 60            # CI mode: non-zero exit on breach

Options:

Flag	Description
`--framework`	Force a sink adapter (e.g. `langgraph`). Auto-detect by default.
`--baseline`	Also inspect this path and use its risk score as the “before”
`--ci`	CI mode: machine output + non-zero exit on breach
`--max-risk`	CI risk-score threshold for a non-zero exit (default: 60)
`--emit-cases`	Also write `aegis-out/cases/cases.json`
`--ingest-verdicts`	Fold `aegis-out/cases/verdicts.json` back into the report

`aegis replay`

Replay a built-in attack against the project using the real scanner, showing the with/without-Aegis outcome.

aegis replay .                                # Replay memory-poisoning demo
aegis replay . --attack memory-poisoning

Options:

Flag	Description
`--attack`	Built-in attack to replay (currently `memory-poisoning`)

Environment Variables

Variable	Description
`AEGIS_API_KEY`	API key (highest priority)
`AEGIS_API_URL`	Server URL
`AEGIS_PROFILE`	Active profile
`AEGIS_NAMESPACE`	Default namespace
`AEGIS_AGENT_ID`	Default agent ID

Exit Codes

Code	Meaning
0	Success
1	General error
2	Connection error
3	Authentication error
4	Not found
5	Validation error

​CLI Reference

​Installation

​Configuration

​aegis init

​aegis new

​aegis explore

​aegis config init

​aegis config show

​aegis config set

​Server Status

​aegis status

​aegis stats

​Memory Operations

​aegis add

​aegis query

​aegis get

​aegis update

​aegis delete

​Voting

​aegis vote

​Playbook

​aegis playbook

​Session Progress

​aegis progress create

​aegis progress update

​aegis progress show

​Feature Tracking

​aegis features create

​aegis features verify

​aegis features fail

​Data Management

​aegis export

​aegis import

​Maintenance

​aegis prune

​Security Analysis

​aegis inspect

​aegis replay

​Environment Variables

​Exit Codes

CLI Reference

Installation

Configuration

`aegis init`

`aegis new`

`aegis explore`

`aegis config init`

`aegis config show`

`aegis config set`

Server Status

`aegis status`

`aegis stats`

Memory Operations

`aegis add`

`aegis query`

`aegis get`

`aegis update`

`aegis delete`

Voting

`aegis vote`

Playbook

`aegis playbook`

Session Progress

`aegis progress create`

`aegis progress update`

`aegis progress show`

Feature Tracking

`aegis features create`

`aegis features verify`

`aegis features fail`

Data Management

`aegis export`

`aegis import`

Maintenance

`aegis prune`

Security Analysis

`aegis inspect`

`aegis replay`

Environment Variables

Exit Codes