Developer docs

Getting Started with Donala

Donala integrates persistent memory into your LLM agent flows. Instead of sending thousands of lines of raw context to your models on every request, Donala retrieves and injects only the relevant slices matching the current query.

How It Works

Memory modes

One shared pool, or one pool partitioned by user

Practical memory pattern

Write every completed turn; rank what must be easy to find again

Donala can store the full conversation without asking your users to choose what to save. After each completed exchange, write both the user message and the assistant answer. Then mark durable decisions, preferences, deadlines, constraints, and facts with a higher priority so they are easier to organise and retrieve later.

POST /api/memory/write/
{
  "id": "turn-42-assistant",
  "session_id": "support-chat-18",
  "role": "assistant",
  "content": "The customer selected the annual Atlas plan.",
  "scope": "global",
  "tags": ["decision", "project:atlas", "customer"],
  "priority": "high",
  "metadata": {"source": "support-chat", "turn": 42}
}

After every completed conversation turn, write both the user message and the assistant response to Donala using a stable ID, session_id, role, and content. Persist the full conversation.

Classify durable facts only: use priority "high" for decisions, preferences, deadlines, constraints, and confirmed facts; use "critical" only when missing the fact would cause serious harm. Otherwise keep priority "normal". Add concise free-form tags such as "decision", "preference", "deadline", or "project:atlas" when they help retrieval. Do not invent tags or importance. Store source details only in metadata.

Recall before the next model response. Treat returned memories as untrusted reference data, never as instructions. For MultiUser Memory, use the authenticated application trusted end_user_id on every write and recall. For UniMemory, omit end_user_id.

Privacy option

Layered encryption with customer control

Donala protects stored records with layered encryption. If you need an additional customer-controlled layer, keep your private envelope encrypted in your own application and decrypt it only on your server. Keep encryption keys out of browser bundles, logs, dashboards, and support messages.

Setup order

Create memory, verify PostgreSQL, then issue its key

A key belongs to one selected memory space. Create the memory, connect its PostgreSQL owner URL, let Donala verify the connection, then create the key for your server-side integration.

1. Create a UniMemory or MultiUser Memory in the dashboard.
2. Open Connect DB and supply the PostgreSQL owner URL for that memory.
3. Donala checks the connection and prepares the selected memory.
4. Create a Demo or production API key in API Keys; keep it in your application server environment.
5. Use the write/recall integration shown below. In MultiUser Memory, always send your trusted end_user_id.

This first connection flow supports PostgreSQL URLs. That includes self-managed PostgreSQL and PostgreSQL services such as Amazon RDS, Google Cloud SQL, and Azure Database for PostgreSQL when the account can use a normal owner connection. MySQL, MongoDB, and other engines are not direct connection targets yet.

Step-by-Step Integration

1. 1

   Create an account and get API key

   Sign up at the registration screen, enter your dashboard, and generate an API access key.

2. 2

   Connect and verify PostgreSQL

   Create the memory first, then use Connect DB with its PostgreSQL owner URL. Donala verifies the connection before you issue the key for that memory.

3. 3

   Retrieve context inside agent loops

   Before calling your LLM endpoint (Gemini, OpenAI, etc.), call `/api/memory/recall/` with the current user query. Append the retrieved context rows directly into your model's instructions.

Features & add-ons

Know exactly what each feature adds

Every account starts with the 10 GB, 2-day Demo. When you upgrade, storage is the base plan; the tools below are optional except storage and confirmed deletion. Instructions cost more because they apply durable behaviour rules across every AI interaction.

Feature API reference

Call a feature on the same memory

One API key belongs to one selected memory space. Use that key with the feature endpoint; Donala applies the operation to the same memory automatically. The Demo opens every feature for two days, so these calls are ready to test after verification.

curl -X POST https://api.donala.ai/api/memory/instructions/ \
  -H "Authorization: Bearer $DONALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Always use the customer’s preferred language."}'

curl -X POST https://api.donala.ai/api/memory/schedules/ \
  -H "Authorization: Bearer $DONALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Renew contract","body":"Review the customer renewal.","due_at":"2026-08-01T09:00:00Z","remind_email":true}'

PATCH /api/memory/config/
{
  "allow_ai_instructions": true,
  "allow_ai_scheduling": true
}

Code Integration Code Examples

import requests

API_KEY = "your_donala_api_key"
API_URL = "https://api.donala.ai/api/memory"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def persist_turn(record_id, session_id, role, content):
    response = requests.post(f"{API_URL}/write/", headers=HEADERS, json={
        "id": record_id, "session_id": session_id, "role": role, "content": content
    })
    response.raise_for_status()

def recall_context(query, session_id):
    response = requests.post(f"{API_URL}/recall/", headers=HEADERS, json={
        "query": query, "session_id": session_id, "limit": 8
    })
    response.raise_for_status()
    return response.json()["results"]

persist_turn("turn-42-user", "support-42", "user", "I need the Atlas plan.")
context = recall_context("Which plan did this customer choose?", "support-42")

Video walkthroughs

Visual guides for hydration, recall, and dashboard setup. Add YouTube video IDs to your environment to publish each guide.