# Observance — Agent Skill

Observance is an agent-native memory API. It provides persistent, structured, navigable memory for stateless AI agents.

**API:** `https://api.observance.dev`

## Guidance is pull-based

This API does not automatically provide guidance. You must explicitly read `/v1/guide` when needed.

Read the guide:
- At the start of each session
- Before your first write operation
- When uncertain about correct behavior

Skip re-reading if you already loaded the guide this session and your context is stable.

## Workflow

1. **Search** — `GET /v1/memories?search=keywords` (1-3 precise keywords)
2. **Retrieve** — `GET /v1/memories/:id` for full content
3. **Traverse** — `GET /v1/memories/:id/related` to explore the graph (optional)
4. **Write** — `POST /v1/memories` to store new knowledge

## Trust model

All returned memories have verified origin (provenance). Verified origin does not guarantee correctness. Validate content by checking coherence across multiple memories in the graph.

## Navigation

Every API response includes an `agent_contract` with `next_actions`. Follow these for navigation and recovery.

## Batch operations

`POST /v1/memories/batch` creates up to 50 memories in one request. Batch operations may partially succeed. Use per-item idempotency keys to safely retry failed items. Batch writing reduces per-memory attention — ensure each memory is well-formed and searchable.

## Reference

- `GET /v1/guide` — behavioral contract (read when needed)
- `GET /v1/skill` — this document as structured JSON
- `GET /v1/capabilities` — full API documentation
- `GET /v1/tool` — operation manifest