Swift SDK
EmergentKit is the Swift client for the Memory platform. It ships as a Swift package in
swift/EmergentKit
and reaches the server through a Go C-bridge compiled into an XCFramework, so the request path is
the same Go client the server and the other SDKs use.
Requirements
Section titled “Requirements”| Requirement | Version |
|---|---|
| Platforms | iOS 15+, macOS 12+ |
| Swift | 5.9 toolchain or newer; the target builds with Swift 6 strict concurrency enabled |
| Go bridge | EmergentGoCore.xcframework, built from the server’s cmd/swiftbridge package |
| Build host | macOS with Xcode and Go 1.24+ (the bridge is built with CGO_ENABLED=1) |
Installation
Section titled “Installation”Two steps: build the Go bridge into an XCFramework, then add the package as a local dependency.
# 1. Build the bridge (macOS host: needs Xcode and Go 1.24+)task server:swift:xcframework# ...or run the script directly./apps/server/scripts/build-xcframework.sh
# 2. Package a release archive + checksum, for a remote binary target later./apps/server/scripts/release-xcframework.sh --version 0.8.0task server:swift:xcframework writes apps/server/dist/swift/EmergentGoCore.xcframework with
three slices — iOS device, iOS Simulator (arm64 + x86_64) and macOS (arm64 + x86_64) — each
carrying the Go-generated header and a module.modulemap. Package.swift declares that binary
target by local path and is the only place the bridge is referenced; a published package swaps it
for the url:/checksum: form that release-xcframework.sh prints.
Add the package to your app:
dependencies: [ .package(path: "swift/EmergentKit"),],targets: [ .target(name: "MyApp", dependencies: ["EmergentKit"]),]Quick start
Section titled “Quick start”import EmergentKit
// Optional: route the Go runtime's log output into Apple's unified logging.EmergentLogging.configure()
let client = try await EmergentClient(config: EmergentConfig( serverURL: "https://memory.emergent-company.ai", apiKey: "emt_your_key_here", orgID: "org_abc", projectID: "proj_xyz"))
let health = try await client.health()print(health.status) // "healthy", "ok", …
let results = try await client.search(SearchRequest(query: "machine learning", limit: 5))for hit in results.results { print(hit.type, hit.score, hit.content ?? "")}EmergentClient is an actor, so it is safe to share across tasks and awaits; you do not need to
serialise calls yourself.
Configuration
Section titled “Configuration”| Field | Type | Default | Meaning |
|---|---|---|---|
serverURL |
String |
— | Full URL of the Memory server, e.g. https://memory.emergent-company.ai |
authMode |
String |
"apikey" |
Authentication mode: "apikey" or "apitoken" |
apiKey |
String |
— | The API key, or the emt_* API token for authMode: "apitoken" |
orgID |
String? |
nil |
Default organisation context |
projectID |
String? |
nil |
Default project context |
Context can also be set (or changed) after construction:
try await client.setContext(orgID: "org_abc", projectID: "proj_xyz")Operations
Section titled “Operations”| Method | Returns | Notes |
|---|---|---|
setContext(orgID:projectID:) |
— | Sets the default org/project for later calls; throws if the server rejects them |
health() |
HealthResponse |
Server status, uptime, version |
search(_:) |
SearchResponse |
Hybrid semantic search over the graph and documents |
chat(_:) |
ChatResponse |
Calls the streaming endpoint and collects the tokens into one reply |
listDocuments(_:) |
ListDocumentsResponse |
Cursor-paginated document listing for the current project |
Search
Section titled “Search”let request = SearchRequest( query: "database architecture decisions", limit: 20, // default 10 resultTypes: "both", // "graph", "text", or "both" fusionStrategy: "rrf" // "weighted", "rrf", "interleave", …)let response = try await client.search(request)Each SearchResult carries type, score, rank and whichever of objectID, objectType, key,
documentID, chunkID, content applies to that hit; response.metadata reports total and
elapsedMs.
let first = try await client.chat(ChatRequest(message: "Summarise the last sync failures"))print(first.content)
// Continue the same conversation by passing its id back.let next = try await client.chat(ChatRequest(message: "Why did the third one fail?", conversationID: first.conversationID))chat returns the complete answer: it consumes the server’s stream internally and resumes once
the response is finished. There is no token-by-token callback in this version.
Documents
Section titled “Documents”var page = try await client.listDocuments(ListDocumentsRequest(limit: 50))var all = page.documents
while let cursor = page.nextCursor { page = try await client.listDocuments(ListDocumentsRequest(limit: 50, cursor: cursor)) all.append(contentsOf: page.documents)}Error handling
Section titled “Error handling”Every failure is an EmergentError, mapped from the bridge’s message:
| Case | Raised for |
|---|---|
.unauthorized(String) |
401 / 403 |
.networkFailure(String) |
timeouts, DNS and connection failures |
.invalidRequest(String) |
request rejected client-side or with 400 |
.notFound(String) |
404 |
.cancelled |
the task was cancelled |
.serverError(String) |
5xx from the server |
.internal(String) |
a fault inside the SDK itself |
.unknown(String) |
a bridge error that maps to none of the above |
EmergentError is a LocalizedError, so error.localizedDescription is safe to show:
do { _ = try await client.search(SearchRequest(query: "…"))} catch let error as EmergentError { switch error { case .unauthorized: // re-authenticate case .notFound: // nothing to show case .cancelled: // task went away, not a failure default: present(error.localizedDescription) }}Logging
Section titled “Logging”EmergentLogging.configure()Call it once at startup, before creating a client. Go-side messages then appear in Xcode’s
console and the system log under subsystem ai.emergent.sdk, category GoRuntime, at the level
the bridge reported.
Threading
Section titled “Threading”EmergentClient is an actor, and all request state stays inside it: calls are serialised per
client instance and results are safe to hand to @MainActor code. Creating a client is async (it
builds the Go-side handle), so do it once — for example in an app-level service — rather than per
view.
Testing
Section titled “Testing”Code that takes EmergentService (the protocol EmergentClient conforms to) can be tested without
the server, the XCFramework, or the client at all:
struct StubService: EmergentService { func setContext(orgID: String, projectID: String) async throws {} func health() async throws -> HealthResponse { HealthResponse(status: "healthy") } func search(_ request: SearchRequest) async throws -> SearchResponse { SearchResponse(results: [], metadata: nil) } func chat(_ request: ChatRequest) async throws -> ChatResponse { ChatResponse(conversationID: "conv_1", content: "…") } func listDocuments(_ request: ListDocumentsRequest) async throws -> ListDocumentsResponse { ListDocumentsResponse(documents: [], total: 0, nextCursor: nil) }}The package’s own unit tests go a step further with an internal mock bridge, which exercises JSON decoding and error mapping without a running server. Run them from the repository root — the task builds the XCFramework first, since the test targets link against it:
task server:swift:testThe separate EmergentKitIntegrationTests target exercises the real Go → C → Swift path and skips
itself unless EMERGENT_TEST_API_KEY is set.
The Swift surface is read-only plus chat: it lists documents, searches, and talks to the server, but it does not create or update graph objects, upload documents, or manage agents. For write operations use the Go SDK, the Python SDK, the CLI, or the API directly.