The usePerceptions hook contains access to information about the soul's recent incoming perceptions.

import { usePerceptions } from "@opensouls/engine"
const exampleProcess: MentalProcess = async ({ workingMemory }) => {
  // get information about the incoming perceptions
  const { invokingPerception, pendingPerceptions } = usePerceptions()
  // rest of the mental process
  // ...
  return workingMemory
export default exampleProcess


The invokingPerception variable contains a copy of the perception that invoked the current mental process to run.

interface perception {
  action: string
  content: string
  name?: string,
  internal?: boolean,
  // other internal properties...

Internal perceptions are generated when a cognitive event is scheduled.

It's common to use the invokingPerception to control different types of execution flow in a mental process.

const { invokingPerception } = usePerceptions()
if (invokingPerception.action === "reacted") {
  // do stuff
} else if (invokingPerception.action === "felt") {
  // do other stuff


The pendingPerceptions object contains a continuously updating copy of all inbound perceptions that have been generated since the current mental process started running.

interface pendingPerceptions {
  current: Perception[]

A mental process can be cancelled or exited to model a behavior like being interrupted by an incoming text using the pendingPerceptions array

const exampleProcess: MentalProcess = async ({ workingMemory }) => {
  let step = initialStep
  // operations on the working memory step ...
  const { pendingPerceptions } = usePerceptions()
  // if any new perceptions came in since the process started, abort by returning the initial step
  if (pendingPerceptions.current.length > 0) {
    return initialStep
  // do the rest of the stuff ...
  return step
export default exampleProcess