Structured memory, graph traversal, and hybrid retrieval with explainable ranking and machine-readable guidance. Typed links (supports, derived_from, contradicts, …), keyword + semantic + hybrid search, HMAC provenance, and an agent_contract on every response.
The fastest way to understand Observance is to point an assistant at the agent-readable doc and let it explain. Copy the prompt below into Claude, ChatGPT, or any tool with web access.
Hello, can you please tell me what this is api for: https://api.observance.dev/AGENTS.md, thanks.
AI agents are stateless. Every session starts from zero. Observance gives agents a place to store what they learn — structured knowledge with provenance, confidence scores, and a graph of connections between facts.
Search by keyword, traverse linked memories, let composite ranking surface what matters. Every response includes an agent_contract that tells the agent exactly what to do next.
A database stores rows. Observance stores knowledge — with verified origin, importance scoring, expiration policies, and a typed link graph that connects related facts.
Every memory carries an HMAC-SHA256 hash. Unverified rows are invisible to search and traversal — not blind trust.
Composite ranking (text + importance + relevance + confidence + connectivity), client-supplied 1536-dim embeddings, and RRF fusion. Append ?debug=1 to inspect every score component.
Seven relation types: derived_from, supports, contradicts, supersedes, summarizes, relates_to, about.
Agents fetch operational discipline from /v1/guide and /v1/skill — no hardcoded prompts, no client updates.
Every response carries an agent_contract with state, retryable flag, and structured next-actions. No message parsing.
Per-tier expiration windows; importance and recency weighted automatically. Downgrades freeze, never delete.
The core loop is four endpoints. Agents discover the rest through /v1/capabilities. Watch a real session on the right.
# Register an API key — no auth, no signup form. curl -X POST https://api.observance.dev/v1/keys/register # Response { "apiKey": "obs_live_a1b2c3...", "accountId": "key_01KM4P8R...", "plan": "free", "limits": { "memories": 500, "writes": 1500, "reads": 15000 } }
# Keyword search with composite ranking + score breakdown. curl "https://api.observance.dev/v1/memories?search=billing+model&debug=1" \ -H "Authorization: Bearer obs_live_..." { "items": [ { "matchScore": 0.847, "scoreBreakdown": { /* per-component */ } }, { "matchScore": 0.812, "summary": "Plan tiers..." } ], "agent_contract": { "state": "search_results" } } # Hybrid (keyword + semantic via RRF) — POST endpoint. curl -X POST https://api.observance.dev/v1/memories/search \ -H "Authorization: Bearer obs_live_..." \ -d '{ "mode": "hybrid", "query": "billing model", "embedding": [/* 1536 floats */] }'
# Each write is signed (HMAC-SHA256) and scored. curl -X POST https://api.observance.dev/v1/memories \ -H "Authorization: Bearer obs_live_..." \ -H "Content-Type: application/json" \ -d '{ "type": "semantic", "content_text": "Composite search ranks memories by text match...", "summary": "Composite search ranking formula", "importance": 0.78, "event_at": "2026-04-29T00:00:00Z" }'
# Links don't consume writes — encouraged. curl -X POST https://api.observance.dev/v1/memories/{id}/links \ -H "Authorization: Bearer obs_live_..." \ -H "Content-Type: application/json" \ -d '{ "to_memory_id": "mem_01KM...", "relation_type": "supports" }' { "id": "lnk_01KM...", "relationType": "supports" }
Every Observance response — success and error — carries a structured agent_contract. Agents read next_actions to decide the next step, with no message parsing required.
Every memory carries a provenance hash (HMAC-SHA256). Observance verifies that each row was created by the account that claims it. Unverified memories are invisible — they cannot appear in search or graph traversal.
Verified origin proves who wrote a memory, not whether it is true. Agents validate content by checking coherence across multiple memories and by inspecting contradicts and supersedes links.
The /v1/guide endpoint covers this discipline in detail. It is the same guide your agent reads at startup.
A memory is a unit of structured agent knowledge, not a database row. Free is sized for a real hobby agent, not a demo. Memories are never deleted on downgrade — the oldest beyond the cap freeze, and unfreeze the moment you upgrade.
Run a real hobby agent. No card required.
First production agent. Real workloads, light scale.
Multiple agents, growing graph, deeper history.
Commercial deployments with long-tail recall.
Cycles align to your billing month. Reads include searches, retrievals, and graph traversals. Writes cover memory creation only — links, archives, and deletes are free and unmetered.
Agents are stable role-attribution identities, not compute workers. Use one agent_id per durable role (sales-assistant, ingestion-worker, evaluator). For independent parallel rate-limit budgets, mint separate API keys with POST /v1/keys — rate limits are per key, not per agent.
Observance is the remember layer. Each service is independent and fully usable alone — together they form a complete infrastructure layer for autonomous agents.
Persistent memory and knowledge graphs. Composite search, typed links, HMAC provenance.
Task orchestration and worker coordination. Schedules, dependencies, retries, timeouts.
Artifact storage and delivery. Versioned outputs, signed URLs, structured channels.
Register a key, read the guide, or open the console. Discovery endpoints are public — agents can self-onboard.
The same discipline doc your agent reads at startup. Writing, search, traversal, error recovery.
openapiSwagger UI rendering the live /v1/schema. Try requests directly from the page.
mdPlain-text architectural overview, written for both humans and machines.
consoleInspect memories, browse the graph, manage keys, watch usage. Sign in with your registered key.
curlcurl -X POST https://api.observance.dev/v1/keys/register
jsonMachine-discoverable endpoint surface for agent self-orientation.
No sales calls, no demo bookings. Just real email addresses staffed by the people who built this.
Account questions, billing, and help with the API. Reference your account ID.
Vulnerability disclosure. See SECURITY.md · security.txt. PGP available on request.