# Observance

> Agent-native memory layer for AI agents. Structured memory storage with a typed knowledge graph, keyword + semantic + hybrid (RRF) retrieval with explainable ranking, HMAC-SHA256 provenance, machine-readable `agent_contract` on every response, and a built-in retrieval-quality eval CLI.

Observance is a REST API for autonomous agents to persist what they learn across stateless sessions. Memories are typed (`episodic` / `semantic` / `procedural`), carry cognitive roles (observation / reflection / fact / rule / skill / preference), live in account-scoped namespaces, and connect through seven typed link relations (`derived_from`, `supports`, `contradicts`, `supersedes`, `summarizes`, `relates_to`, `about`). Every response includes an `agent_contract` with `state`, `retryable`, and `next_actions` so callers can act on it without parsing prose.

The fastest way to understand the API is to read [AGENTS.md](https://api.observance.dev/AGENTS.md) — written for both humans and machines.

## Discovery

- [AGENTS.md](https://api.observance.dev/AGENTS.md): Architectural overview. Authentication, memory lifecycle, search, traversal, links, agents, billing. Plain-text, agent-readable.
- [/.well-known/agent.json](https://api.observance.dev/.well-known/agent.json): Entry-point manifest — links to every discovery resource.
- [/v1/capabilities](https://api.observance.dev/v1/capabilities): Full machine-readable surface — endpoints, error codes, rate limits, plan limits, action codes, traversal/search contracts.
- [/v1/skill](https://api.observance.dev/v1/skill): Onboarding manifest — when to read `/v1/guide`, how to search, how to write, agent identity discipline.
- [/v1/guide](https://api.observance.dev/v1/guide): Operational discipline — core rules, reading/writing/search discipline, agent identity, linking, operations.

## API

- [POST /v1/keys/register](https://api.observance.dev/v1/keys/register): Register an API key. No signup, no card on Free tier. Returns `apiKey` (shown once) and `accountId`.
- [/v1/schema](https://api.observance.dev/v1/schema): OpenAPI 3.1 JSON schema.
- [/v1/tool](https://api.observance.dev/v1/tool): MCP-compatible tool manifest.
- [Swagger UI](https://api.observance.dev/docs): Live API docs rendered from `/v1/schema`. Try requests directly from the page.

## Memory operations

- `POST /v1/memories` — Create a memory. Auto-provisions a default agent on first write.
- `GET /v1/memories?search=<query>&debug=1` — Keyword search with composite ranking; `?debug=1` returns per-component score breakdown.
- `POST /v1/memories/search` — Multi-mode search (`keyword` / `semantic` / `hybrid`). Hybrid uses Reciprocal Rank Fusion over keyword and semantic ranked lists.
- `PUT /v1/memories/:id/embedding` — Upload a client-supplied 1536-dimensional embedding (cosine, normalized). The API does not generate embeddings.
- `GET /v1/memories/:id/related?depth=1..3&max_nodes=1..200` — Graph traversal with cycle-safe walks; supports direction, relation_type, and order params.

## Pricing

- [Pricing](https://observance.dev/#pricing): Free $0 (500 memories, 1.5K writes/cycle, 15K reads/cycle, 30d retention, 1 agent), Solo $9 (2.5K mem, 10K writes, 100K reads, 90d, 3 agents), Pro $29 (25K mem, 75K writes, 750K reads, 180d, 10 agents), Business $79 (100K mem, 250K writes, 2.5M reads, 365d, 25 agents).

## Suite

- [The agent-infrastructure suite](https://observance.dev/#suite): Observance is the **remember** layer. Siblings: **Orchestrion** (decide — task orchestration) and **OutputLayer** (produce — artifact storage).

## Optional

- [Developer console](https://console.observance.dev): Browse memories, debug search rankings, manage API keys.
- [Eval CLI](https://api.observance.dev/AGENTS.md#eval): Built-in retrieval-quality eval — `npm run eval:seed` then `npm run eval` to run a curated question suite against your account.