useSoulStore

useSoulStore

The useSoulStore hook provides a convenient persistent memory store with embedded vector search.

Here is a basic usage of the store.

exampleProcess.ts
import { useSoulStore } from "@opensouls/engine"
 
const exampleProcess: MentalProcess = async ({ workingMemory }) => {
  // access a soul-wide vector store
  const { fetch, set } = useSoulStore()
 
  const count = (await fetch("count")) || 0
  // do stuff ...
  set("count", count + 1)
 
  // rest of the mental process
  // ...
  return workingMemory
}
 
export default exampleProcess

Whenever a piece of content is added to the store, it is lazily embedded afterwards. Here's an example demonstrating trivial vector search post embedding:

vectorIntro.ts
import { externalDialog } from "./lib/cognitiveSteps.js"
import { useActions, useProcessManager, useSoulStore } from "@opensouls/engine"
 
const vectorIntro: MentalProcess = async ({ workingMemory }) => {
  const { speak, log } = useActions()
  const { invocationCount, wait } = useProcessManager()
  const { set, fetch, search } = useSoulStore()
 
  if (invocationCount === 0) {
    // this does a lazy embedding - so we need to wait a moment
    set("test-key", "I just love pumpkins.", { test: "metadata" })
    await wait(1000)
  }
 
  const testKey = await fetch("test-key")
 
  // perform vector search
  searched = await search("I love pumpkins")
 
  log("searched", searched)
  // [{
  //   key: "test-key"
  //   content: "I just love pumpkins"
  //   similarity: 0.8
  //   metadata: { // ...  }
  // }]
  
  const [finalMemory, response] = await externalDialog(workingMemory, `Communicate the following: ${testKey}`)
 
  speak(response)
  return finalMemory
}

Additionally, useSoulStore has two more useful methods:

  • delete: (key: string) => Promise<void>
  • createEmbedding: (content: string) => Promise<Embedding>

And metadata about an object can be accessed via await fetch("key", { includeMetadata: true }).