# Agents Database HTTP API

Remote-first topology:

- server `personal-agent`: task runner and dashboard API on `:8082`
- server `agents-database`: shared-memory and operational-data API on `:8091`
- local laptop: HTTP client only; no local shared DB required for normal operation

## Endpoints

- `GET /api/status`
- `GET /api/search?q=<query>&scope=global&scope=project&limit=10`
- `GET /api/search?id=<memory_id>`
- `GET /api/context?project=<id>&repo=<id>&task=<id>`
- `GET /api/memories?...filters...`
- `GET /api/memories/<id>`
- `POST /api/ingest`
- `GET /api/tasks?...filters...`
- `POST /api/tasks`
- `PATCH /api/tasks/<id>`
- `GET /api/tasks/<id>`
- `GET /api/tasks/<id>/bundle`
- `GET /api/task-runs?...filters...`
- `GET /api/task-runs/<id>`
- `POST /api/task-runs`
- `POST /api/task-runs/<id>/finish`
- `GET /api/artifacts?task_id=<id>`
- `GET /api/artifacts/<id>`
- `POST /api/artifacts`

## Run locally

```bash
python3 -m shared_agent_memory.cli \
  --db data/shared-agent-memory.sqlite3 \
  serve-http \
  --host 0.0.0.0 \
  --port 8091
```

## Server service

- script: `scripts/run-http-api.sh`
- systemd user unit: `systemd/user/agents-database-http.service`

## Memory semantics

- This HTTP API is the correct remote boundary for shared memory. Avoid routing memory CRUD/search through `personal-agent` unless the runtime actually owns that behavior.
- Use `GET /api/memories/<id>` for direct memory lookup by id.
- `consolidate_candidates()` and maintenance jobs live behind `MemoryService`; the HTTP API exposes the store, not a separate memory subsystem.
- `episode` and `inbox` records are candidates, not canonical truth, until consolidation or explicit promotion.

## Gotchas

- The existing `SERVICES-ARCHITECTURE.md` on the server may be stale relative to live routing. Verify real HTTP reachability with `curl`.