> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Common tasks

> Useful one-liners for local Engine development.

A growing collection of commands you'll reach for repeatedly when
developing against a local Engine. Copy-paste-friendly.

All examples assume:

```bash theme={null}
export ENGINE_URL=http://localhost:8000
export ENGINE_KEY=dev-engine-key
```

## Engine lifecycle

### Start

```bash theme={null}
docker compose up engine
```

### Start in background

```bash theme={null}
docker compose up -d engine
```

### Stop

```bash theme={null}
docker compose down
```

### Stop and wipe the brain

```bash theme={null}
docker compose down --volumes
```

The `--volumes` flag removes the `engine_data` Docker volume — the
brain SQLite file and everything in it. Use this for a clean slate.

### Rebuild after code changes

```bash theme={null}
docker compose build engine && docker compose up engine
```

### Tail logs

```bash theme={null}
docker compose logs -f engine
```

## Brain inspection

### List tables

```bash theme={null}
docker compose exec engine sqlite3 /data/brain.sqlite '.tables'
```

### Count rows in a table

```bash theme={null}
docker compose exec engine sqlite3 /data/brain.sqlite \
  'SELECT COUNT(*) FROM episodes'
```

### Browse recent episodes

```bash theme={null}
docker compose exec engine sqlite3 -header -column /data/brain.sqlite \
  'SELECT id, key, description, created_at FROM episodes
   ORDER BY created_at DESC LIMIT 10'
```

### Browse recent trajectories

```bash theme={null}
docker compose exec engine sqlite3 -header -column /data/brain.sqlite \
  'SELECT id, thread_id, task_id, created_at FROM trajectories
   ORDER BY created_at DESC LIMIT 5'
```

### Reset memory (keep schema)

```bash theme={null}
docker compose exec engine sqlite3 /data/brain.sqlite \
  'DELETE FROM episodes; DELETE FROM knowledge_store;
   DELETE FROM social_graph_nodes; DELETE FROM working_memory_log;
   DELETE FROM trajectories;'
```

This wipes memory but keeps the schema and migrations applied. Faster
than rebuilding the volume.

## Configuration changes

### Edit env, restart

```bash theme={null}
$EDITOR .env
docker compose up -d engine  # picks up the new .env
```

If you set environment variables inline (not in `.env`), you'll need
to recreate the container:

```bash theme={null}
ENGINE_LOG_LEVEL=DEBUG docker compose up -d engine
```

### Reload the catalog without restart

```bash theme={null}
curl -X POST "$ENGINE_URL/admin/reload-catalog" \
  -H "X-Engine-Key: $ENGINE_KEY"
```

Use after editing agent definitions, skill definitions, or tool entries
in `catalog/`.

### Reload the soul template

```bash theme={null}
curl -X POST "$ENGINE_URL/admin/reload-core-soul" \
  -H "X-Engine-Key: $ENGINE_KEY"
```

## Quick API tests

### Health check

```bash theme={null}
curl -fsS "$ENGINE_URL/health" | jq
```

### One-shot execute

```bash theme={null}
curl -N -X POST "$ENGINE_URL/execute" \
  -H "X-Engine-Key: $ENGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Say hi.","task_id":"smoke-1"}'
```

### List MCP servers

```bash theme={null}
curl -fsS "$ENGINE_URL/assets/servers" \
  -H "X-Engine-Key: $ENGINE_KEY" | jq
```

### Search knowledge

```bash theme={null}
curl -fsS -X POST "$ENGINE_URL/memory/knowledge/search" \
  -H "X-Engine-Key: $ENGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"prefer","limit":5}' | jq
```

### Trigger a Learning Centre batch

```bash theme={null}
curl -X POST "$ENGINE_URL/admin/lc/trigger" \
  -H "X-Engine-Key: $ENGINE_KEY"
```

Useful when you want trajectories from recent dev runs to consolidate
into long-term memory immediately.

## Tests

### Run the full test suite

```bash theme={null}
docker compose run --rm test pytest tests/ --tb=short
```

### Run one test file

```bash theme={null}
docker compose run --rm test pytest tests/test_agent_loop.py --tb=short
```

### Run one test by name

```bash theme={null}
docker compose run --rm test pytest -k test_compaction_handles_overflow
```

### Run with verbose output

```bash theme={null}
docker compose run --rm test pytest tests/ -vv
```

## Switching configurations

### Switch LLM provider

In `.env`:

```bash theme={null}
LLM_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL=gpt-5.4
OPENAI_API_KEY=sk-...
```

Then `docker compose up -d engine`.

### Use a smaller model for development

Set in `.env`:

```bash theme={null}
LLM_MODEL=claude-haiku-4-5-20251001
```

Cheaper and faster for iteration. Ship with the production model.

### Disable a feature flag

```bash theme={null}
REACTIVE_COMPACT_ENABLED=false
```

Don't forget the values are `"true"`/`"false"` strings, not booleans.

## Dev shortcuts

### Watch logs filtered by task

```bash theme={null}
docker compose logs -f engine | grep task-001
```

### See requests in real time with low log level

```bash theme={null}
ENGINE_LOG_LEVEL=DEBUG docker compose up engine
```

DEBUG logs include MCP traces, model parameters, and context-assembly
steps. Noisy but useful when investigating a specific call.

### Curl with pretty SSE

```bash theme={null}
curl -N -X POST "$ENGINE_URL/execute" \
  -H "X-Engine-Key: $ENGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"hi","task_id":"demo"}' \
  | grep -E '^(event|data):' \
  | sed 's/^data: //'
```

## See also

* [Quickstart](./quickstart) — first-time setup.
* [Troubleshooting](./troubleshooting) — when things go wrong.
* [Environment variables](../config/env-vars) — every knob.