Skip to main content
Welcome to the MemMachine TypeScript SDK. This library provides a seamless, type-safe way to integrate MemMachine’s long-term memory capabilities into your Node.js or browser-based applications. With this SDK, you can easily store, retrieve, and manage AI memories without worrying about the underlying REST API complexities.

​
Key Capabilities

  • Memory Lifecycle: Effortlessly add, search, and manage memories with natural language.
  • Project Isolation: Organize data into distinct projects and organizations.
  • Type Safety: Built-in TypeScript definitions ensure your data structures are always correct.
  • Resilient Design: Robust error handling and health checks to keep your integration running smoothly.

​
Quick Start

1

Install the Package

Add MemMachine to your project using your favorite package manager:
npm install @memmachine/client
2

Initialize and Use

The SDK follows a hierarchical structure: Client → Project → Memory. Here is a quick example of how to store your first memory and search it later.
import MemMachineClient, { MemMachineAPIError } from '@memmachine/client'

async function run() {
  const client = new MemMachineClient({ base_url: 'https://your-base-url' })

  // Create a MemMachineProject instance
  const project = client.project({ org_id: 'demo_org', project_id: 'demo_project' })

  // Create the project with config options on the MemMachine server if it does not exist
  // await project.create({ description: 'Demo Project' })

  // Create a MemMachineMemory instance for the project
  const memory = project.memory()

  try {
    // Add a memory
    await memory.add('I like pizza and pasta')

    // Search memories
    const result = await memory.search('What do I like to eat?')
    console.dir(result, { depth: null })
  } catch (err) {
    if (err instanceof MemMachineAPIError) {
      // Handle error
      console.error(err.message)
    }
  }
}

run()

​
Explore the SDK

The MemMachine SDK is organized into three primary classes. Click a class below to view its full technical reference, including parameters and return types.

MemMachineClient

The entry point. Use this to connect to the server and manage high-level project lists.

MemMachineProject

The project manager. Handles project creation, metadata, and memory counts.

MemMachineMemory

The memory engine. Where you add, search, and manage individual memories.

​
Supporting References

​
Data Types & Configuration

Understanding the data structures is key to a smooth integration. These references define how you configure your environment and the shape of the data returned by the memory engine.
  • Client Configuration: Manage connection settings, authentication, and server health status.
  • Project Context: Define organization IDs, project IDs, and project creation settings.
  • The Workspace: Explore project metadata and manage the active memory scope.
  • Storing Memory: Input parameters and result schemas for adding new episodic data.
  • Retrieving Memory: Search query configurations and semantic search result models.
  • Memory Structures: The core data models for Episode and Semantic memory objects.
  • Types & Roles: Allowed values for MemoryType (episodic/semantic) and MemoryProducerRole (user/assistant/system).

​
Error Handling

Reliable apps need good error handling. We provide a custom error class to help you catch and debug API-specific issues.
  • MemMachineAPIError: Catch this to access specific error messages and status codes returned by the MemMachine server.

​
Contributing & Development

If you are looking to contribute to the SDK or run local tests, follow these steps:
  1. Install Dependencies: npm install
  2. Build the Package: npm run build
  3. Run Unit Tests: npm run test
  4. Try the Demo: Execute npm run example to see a local script in action.

​
License

MemMachine REST Client is open-source software licensed under the Apache-2.0 License.