Engine Core

Working Memory for AI Souls

The Soul Engine provides developers with straightforward and powerful tools for guiding the cognitive processes of large language models (LLMs), making it simpler to craft more dynamic and compelling AI souls.

The Engine provides WorkingMemory and cognitiveSteps for managing context as core abstractions. Each cognitiveStep operates on WorkingMemory, treating every interaction as a distinct transformation. This method ensures a structured and coherent progression of context, allowing for a more predictable and streamlined way to navigate an AI soul's thought process. The result is a more consistent and intuitive interaction flow.

The speak action in the soul engine is a helper function which dispatches an InteractionRequest with the action says.

The core concepts are:

• WorkingMemory - a collection of Memory objects that provides lots of ways to immutably transform memory.
• cognitiveStep - a function that transforms a WorkingMemory, adds to its memories, and returns a response. You can think of these functions as thinking, speaking, noticing, etc.
• processor - a class for calling out to an LLM and fetching a response.

At its most basic, you perform a CognitiveStep on a WorkingMemory and receive both a fully-typed response (based on the schema of your cognitiveStep) and a new WorkingMemory.

CognitiveSteps use a processor to call out to a model that provides reasoning capabilities. OpenAI (and all compatible AIs) as well as Anthropic are supported directly in the library.

Simple Example

Using WorkingMemory and cognitive steps can be thought of as building up a set of memories, and then performing functional, append-only manipulations on those memories. Here is a simple example that initializes a WorkingMemory with memories of being a helpful AI assistant and applies a cognitive step to process new messages.

import { WorkingMemory, ChatMessageRoleEnum, Memory } from "@opensouls/engine";
import { externalDialog } from "./lib/cognitiveSteps.js";
 
// Initialize WorkingMemory with initial memories
let workingMemory = new WorkingMemory({
  soulName: "A Helpful Assistant",
  memories: [
    {
      role: ChatMessageRoleEnum.System,
      content: "You are modeling the mind of a helpful AI assistant",
    },
  ],
});
 
// Then, during an event loop, withReply(...) would be called with a memory of each new message:
async function withReply(workingMemory: WorkingMemory, newMessage: Memory): Promise<WorkingMemory> {
  // externalDialog is a cognitiveStep defined in another function.
  const [updatedMemory, response] = await externalDialog(workingMemory, newMessage);
  console.log("AI:", response);
  return updatedMemory;
}