# Haskell SDK

Using SurrealDB Agent Memory from Haskell applications.

The SurrealDB Agent Memory client ships as the `surrealdb-spectron` package in the [SurrealDB Haskell SDK](https://github.com/surrealdb/surrealdb.haskell). It is a typed client for the SurrealDB Agent Memory platform: store and recall memories, drive the chat loop, and manage documents, entities, sessions, lifecycle, traces, principals, scopes, and keys.

> [!NOTE]
> `Spectron` was the project name for SurrealDB Agent Memory. These type names
> will be renamed in a future release.

## Installation

There are no package-manager releases yet, so add the package from the repository. With cabal, in `cabal.project`:

```cabal
packages: .

source-repository-package
  type: git
  location: https://github.com/surrealdb/surrealdb.haskell
  subdir: surrealdb-spectron
```

Then add `surrealdb-spectron` to your component's `build-depends`. The project builds with GHC 9.4 and 9.6.

## Client construction

```haskell
{-# LANGUAGE OverloadedStrings #-}

import Spectron

main :: IO ()
main = do
  client <- newSpectron
    (defaultSpectronOptions "acme-prod" "sk_your_api_key" "https://api.spectron.example")
  ...
```

`defaultSpectronOptions` takes the context id, the API key, and the endpoint.

## Remember, recall, and chat

```haskell
  -- Store a memory.
  _ <- remember client "Alice moved to Berlin" defaultRememberOptions

  -- Recall relevant memories.
  answer <- recall client "Where does Alice live?" defaultRecallOptions
  print answer

  -- Chat with the memory loop.
  reply <- chat client "What do you know about me?" defaultChatOptions
  print reply
```

The client also exposes `context`, `reflect`, and `forget`, alongside the document, entity, session, lifecycle, trace, principal, scope, and key operations.

## Delegation

Act on behalf of another principal, which sends the `X-Spectron-On-Behalf-Of` header:

```haskell
  let delegated = onBehalfOf client "principal:alice"
  _ <- remember delegated "note for Alice" defaultRememberOptions
```

## Errors

The SurrealDB Agent Memory client throws `SpectronError`, classified by HTTP status into kinds such as `AuthFailed`, `ScopeRejected`, `RateLimited`, and `ServerFailed`.