# Aether

> Managed RAG API for AI applications. Store documents, run hybrid vector + keyword search, and ground LLM answers in your own content. SDKs for Python, TypeScript, Go, and .NET.

## Quickstart

Install the SDK for your language:

```bash
# Python
pip install aether-ai

# TypeScript
npm install @aether-ai/sdk

# Go
go get github.com/quintessence-group/aether-sdk-go

# .NET
dotnet add package AetherDb.Sdk
```

Create an API key at https://platform.aetherdb.ai/api-keys and pass it to the client when you construct it — load it from an environment variable, .env file, or your secrets manager.

The client surface is flat: `insert_text` (raw text) or `insert` (a file path) to add documents, `search` for ranked matches, and `retrieve` for matches with their full text inlined for a prompt. Each hit carries `score` (0-100, higher is better) and the matched `passage`; `retrieve` adds the full `content`.

For per-user or per-agent memory, use the `Memory` facade in the current Python and TypeScript SDKs. It scopes `remember`, `recall`, `list`, and `forget_all` / `forgetAll` to one `entity_id`; use raw `AetherClient` when you need direct document and search control.

Insert a document and ground an answer in it (Python):

```python
import os
from aether import AetherClient

client = AetherClient(api_key=os.environ["AETHER_API_KEY"])
client.insert_text("Aether stores documents and runs RAG search.", filename="notes.txt")

# retrieve() returns the matched documents with their full text, ready for a prompt
results = client.retrieve("What does Aether do?", k=3)
for hit in results:
    print(hit.score, hit.content)
```

Insert a document and ground an answer in it (TypeScript):

```typescript
import { AetherClient } from '@aether-ai/sdk'

const client = new AetherClient({ apiKey: process.env.AETHER_API_KEY })
await client.insertText('Aether stores documents and runs RAG search.', { filename: 'notes.txt' })

// retrieve() returns the matched documents with their full text, ready for a prompt
const results = await client.retrieve('What does Aether do?', 3)
for (const hit of results) {
  console.log(hit.score, hit.content)
}
```

Store and recall entity-scoped memory (Python):

```python
import os
from aether import Memory

memory = Memory("user-42", api_key=os.environ["AETHER_API_KEY"])
memory.remember("Prefers concise weekly summaries")

for item in memory.recall("communication style", k=3):
    print(item.score, item.text)
```

Store and recall entity-scoped memory (TypeScript):

```typescript
import { Memory } from '@aether-ai/sdk'

const memory = new Memory('user-42', { apiKey: process.env.AETHER_API_KEY })
await memory.remember('Prefers concise weekly summaries')

const memories = await memory.recall('communication style', { k: 3 })
for (const item of memories) {
  console.log(item.score, item.text)
}
```

### Full quickstarts and platform on-ramps

Copy-paste quickstarts and per-platform guides for wiring Aether in from an AI coding agent (Cursor, Lovable, Bolt, v0):

- [Python quickstart](https://docs.aetherdb.ai/docs/guides/quickstart-python) — install → working memory in under 10 minutes
- [TypeScript quickstart](https://docs.aetherdb.ai/docs/guides/quickstart-typescript) — install → working memory in under 10 minutes
- [Add Aether to a Cursor project](https://docs.aetherdb.ai/docs/integrations/cursor)
- [Add Aether to a Lovable app](https://docs.aetherdb.ai/docs/integrations/lovable)
- [Add Aether to a Bolt app](https://docs.aetherdb.ai/docs/integrations/bolt)
- [Add Aether to a v0 app](https://docs.aetherdb.ai/docs/integrations/v0)

## Core API

Every authenticated endpoint takes `Authorization: Bearer <api-key>`.

### [Documents](https://docs.aetherdb.ai/docs/api/documents)

- `GET /documents` — List active documents with `offset` and `limit` pagination.
- `POST /documents` — Insert a synchronous text document or other sync-safe payload.
- `GET /documents/{id}` — Fetch document metadata by `doc_id`.
- `PUT /documents/{id}` — Replace a document's content and re-index it.
- `DELETE /documents/{id}` — Soft-delete by default; pass `hard=true` for irreversible hard deletion.
- `GET /documents/{id}/download` — Download the original document bytes.
- `POST /documents/{id}/restore` — Restore a soft-deleted document.
- `POST /documents/{id}/reembed` — Re-chunk and re-embed an existing document, optionally with a new model or chunking config.
- `POST /documents/batch` — Insert multiple text documents in one request.
- `POST /documents/embed` — Insert a document with caller-supplied embeddings.
- `POST /documents/async` — Queue background ingestion for binary or larger documents.
- `GET /documents/jobs/{job_id}` — Poll an async ingestion job.

### [Search & Retrieval](https://docs.aetherdb.ai/docs/api/search)

- `GET /search` — Search by natural-language query.
- `POST /search/embed` — Search by caller-provided embedding vector.
- `POST /search/batch` — Run multiple natural-language searches.

### [Errors](https://docs.aetherdb.ai/docs/api/errors) — HTTP status codes, error response format, and retry guidance.

### [Models](https://docs.aetherdb.ai/docs/api/models) — Explore the strongly typed return objects defined by the Aether SDK.

## Introduction

- [Getting started](https://docs.aetherdb.ai/) — Learn how to get started with Aether.
- [What can I build?](https://docs.aetherdb.ai/docs/guides/use-cases) — Real things you can build with Aether, explained without jargon.
- [Concepts](https://docs.aetherdb.ai/docs/concepts) — Plain-language explanations of the terms you'll see in these docs.
- [Installation](https://docs.aetherdb.ai/docs/installation) — This guide covers getting your API key and installing an SDK for your language.

## Guides

- [Zero to chatbot](https://docs.aetherdb.ai/docs/guides/zero-to-chatbot) — Build a working AI chatbot grounded in your own documents. One file. No frameworks.
- [Python quickstart](https://docs.aetherdb.ai/docs/guides/quickstart-python) — Install the Python SDK and give your app working memory in under 10 minutes — copy, paste, run.
- [TypeScript quickstart](https://docs.aetherdb.ai/docs/guides/quickstart-typescript) — Install the TypeScript SDK and give your app working memory in under 10 minutes — copy, paste, run.
- [Go quickstart](https://docs.aetherdb.ai/docs/guides/quickstart-go) — Build a RAG chatbot in Go with zero frameworks. One file, one dependency.
- [.NET quickstart](https://docs.aetherdb.ai/docs/guides/quickstart-csharp) — Install the .NET SDK, insert a document, search it, and handle API errors with async C#.
- [Quickstart: 5-min RAG](https://docs.aetherdb.ai/docs/guides/quickstart-rag) — Go from zero to a working RAG pipeline in under five minutes.
- [Tuning retrieval](https://docs.aetherdb.ai/docs/guides/tuning-retrieval) — How to pick `k`, interpret search score, filter weak matches, and decide when to reach for the lower-level `search()` primitive.
- [Filtering by time](https://docs.aetherdb.ai/docs/guides/filtering-by-time) — How to scope search, retrieval, and list results to a time window with `since`, `until`, and `last_n_days` — and why combining a time window with an entity or tag filter is the highest-leverage query for longitudinal memory.
- [Multi-tenant patterns](https://docs.aetherdb.ai/docs/guides/multi-tenancy) — How to keep each of your customers' documents and memory separate on Aether — server-enforced isolation with partitions, hard isolation with workspaces, and tags for organizing the rest.
- [Use with Cursor](https://docs.aetherdb.ai/docs/guides/cursor) — Tips for building Aether apps with Cursor, Windsurf, and other AI code editors.
- [Authentication](https://docs.aetherdb.ai/docs/guides/authentication) — Authenticate by giving an Aether SDK an API key. The SDK sends authenticated requests for you.
- [CLI reference](https://docs.aetherdb.ai/docs/guides/cli) — Manage documents and run searches from the terminal.

## Use in ChatGPT & Claude

- [Aether as an MCP connector](https://docs.aetherdb.ai/docs/connectors) — Use your Aether knowledge base directly inside Claude and ChatGPT — no code required.
- [Connect to Claude](https://docs.aetherdb.ai/docs/connectors/claude) — Add Aether to Claude as a custom connector and search your knowledge base in any conversation.
- [Connect to ChatGPT](https://docs.aetherdb.ai/docs/connectors/chatgpt) — Add Aether to ChatGPT so you can search and update your knowledge base while you chat.
- [What you can do](https://docs.aetherdb.ai/docs/connectors/tools) — Once Aether is connected, you can build and search your knowledge base in plain language — just by asking.
- [Connection & privacy](https://docs.aetherdb.ai/docs/connectors/privacy) — You stay in control of what your assistants can see and do — and you can cut off access at any time.

## Integrations

- [Overview](https://docs.aetherdb.ai/docs/integrations) — Use Aether as the retrieval layer for your favorite AI provider.
- [Anthropic Claude](https://docs.aetherdb.ai/docs/integrations/anthropic) — Build retrieval-augmented generation pipelines by combining Aether's vector search with Anthropic Claude's language models.
- [OpenAI](https://docs.aetherdb.ai/docs/integrations/openai) — Build retrieval-augmented generation pipelines by combining Aether's vector search with OpenAI GPT-4o.
- [Azure OpenAI](https://docs.aetherdb.ai/docs/integrations/azure-openai) — Build enterprise RAG pipelines using Aether's vector search with Azure-hosted OpenAI models.
- [Vercel AI SDK](https://docs.aetherdb.ai/docs/integrations/vercel-ai) — Build streaming chat and agentic RAG in Next.js by pairing Aether's vector search with the Vercel AI SDK.
- [xAI Grok](https://docs.aetherdb.ai/docs/integrations/xai-grok) — Build retrieval-augmented generation pipelines by combining Aether's vector search with xAI's Grok models via the OpenAI-compatible API.
- [LangChain](https://docs.aetherdb.ai/docs/integrations/langchain) — Use Aether as a LangChain retriever to build RAG chains with any LLM provider.
- [LlamaIndex](https://docs.aetherdb.ai/docs/integrations/llamaindex) — Use Aether as a LlamaIndex retriever to power query engines with semantic document search.
- [CrewAI](https://docs.aetherdb.ai/docs/integrations/crewai) — Build a CrewAI crew whose research is grounded in your Aether document store — and whose findings flow back into it.
- [Semantic Kernel](https://docs.aetherdb.ai/docs/integrations/semantic-kernel) — Build AI plugins with Semantic Kernel that retrieve grounded context from Aether.

## AI app builders

- [Cursor](https://docs.aetherdb.ai/docs/integrations/cursor) — Wire Aether memory and retrieval into an app you're building with Cursor.
- [Lovable](https://docs.aetherdb.ai/docs/integrations/lovable) — Wire Aether memory and retrieval into a full-stack app you're building with Lovable.
- [Bolt](https://docs.aetherdb.ai/docs/integrations/bolt) — Wire Aether memory and retrieval into a full-stack app you're building with Bolt (bolt.new).
- [v0](https://docs.aetherdb.ai/docs/integrations/v0) — Wire Aether memory and retrieval into a React/Next.js app you're building with v0.

## Examples

- [Overview](https://docs.aetherdb.ai/docs/examples) — A full-stack web application for uploading, browsing, searching, and chatting with your documents — built with Aether.
- [Python (FastAPI)](https://docs.aetherdb.ai/docs/examples/python) — Build a knowledge base manager with FastAPI and the Aether Python SDK.
- [TypeScript (Express)](https://docs.aetherdb.ai/docs/examples/typescript) — Build a Knowledge Base Manager API with Express and the Aether TypeScript SDK.
- [Go (net/http)](https://docs.aetherdb.ai/docs/examples/go) — A complete Knowledge Base Manager built with Go's standard library and the Aether Go SDK — no frameworks, just `net/http`.
- [C# (ASP.NET)](https://docs.aetherdb.ai/docs/examples/csharp) — Build a knowledge base REST API in C# using ASP.NET Core Minimal API and the Aether .NET SDK.

## Resources

- [What's new](https://docs.aetherdb.ai/docs/guides/changelog) — SDK releases, API changes, and notable improvements to Aether.
- [Pricing](https://docs.aetherdb.ai/docs/pricing)
- [Limits & quotas](https://docs.aetherdb.ai/docs/guides/limits) — Document, storage, and rate limits for the Aether API.
- [Troubleshooting](https://docs.aetherdb.ai/docs/guides/troubleshooting) — Solutions to common problems when using Aether.