soulgraph memory

memory 101

why? agents feel most real when they grow through experience, just like we do. memories shape who we become, and soulgraph attempts to apply this to agents, enabling developers to create agents that feel increasingly personal while remaining predictable and consistent.

how does it work? each user<>agent interaction creates immutable memories, tagged with emotional context and importance. these memories stay constant, like a true record of history, while the agent's personality traits evolve naturally through these experiences. this creates a foundation for agents to adapt meaningfully to each user.

interactions are observed by soulgraph, and processed into memories stored with temporal ordering, emotional valence and importance scoring. the personality evolution follows clear rules you can tune and monitor, making it easy to create agents that grow through user interaction while maintaining reliable memory retrieval.

memories are immutable, personalities evolve, and your agents develop naturally through real experiences. we think this is the right way to build agents that feel alive (and have a soul).

try it out in the playground on https://soulgra.ph

soulgraph memory architecture

memory structure

memory fragment a raw observation or reflection from an interaction

consolidated memory a processed long-term memory combining multiple fragments

memory graph a collection of all memories and their relationships

memory formation flow

observation

soulgraph observes user <> agent interaction and creates memory fragments

{
  "type": "observation",
  "content": "User expressed anxiety about mathematics",
  "timestamp": 1703030400000,
  "importance": 0.8,
  "emotional_valence": -0.2,
  "context": {
    "user_state": "anxious",
    "agent_state": "empathetic",
    "topic": "mathematics",
    "interaction_type": "learning_support"
  }
}

reflection

soulgraph reflects on observation based on agent personality

{
  "type": "reflection",
  "content": "User trusts me to help with vulnerable learning moments",
  "timestamp": 1703030401000,
  "importance": 0.9,
  "context": {
    "insight_type": "relationship_development",
    "personality_trait": "empathy"
  }
}

consolidation

are combined into persistent memories

{
  "id": "mem_01HKG9X5NJWT",
  "core_memory": "Established supportive relationship helping user overcome math anxiety",
  "fragments": [ /* observation and reflection fragments */ ],
  "importance_score": 0.85,
  "emotional_signature": {
    "valence": 0.3,
    "intensity": 0.7
  }
}

consolidated memory

observations and memory fragments are combined and processed into a consolidated memory object

{
  "id": "mem_01HKG9X5NJWT",
  "core_memory": "Established supportive relationship helping user overcome math anxiety",
  "fragments": [
    {
      "type": "observation",
      "content": "User expressed anxiety about mathematics",
      "timestamp": 1703030400000,
      "importance": 0.8,
      "emotional_valence": -0.2,
      "context": {
        "user_state": "anxious",
        "agent_state": "empathetic",
        "topic": "mathematics"
      }
    },
    {
      "type": "reflection",
      "content": "User trusts me to help with vulnerable learning moments",
      "timestamp": 1703030401000,
      "importance": 0.9,
      "emotional_valence": 0.6,
      "context": {
        "insight_type": "relationship_development",
        "personality_trait": "empathy"
      }
    }
  ],
  "connections": [
    "mem_01HKG9X5MJKT", // related memory about teaching style
    "mem_01HKG9X5PQRS"  // related memory about user's learning progress
  ],
  "emotional_signature": {
    "valence": 0.3,     // overall emotional tone
    "intensity": 0.7    // emotional significance
  },
  "importance_score": 0.85,
  "creation_date": 1703030400000,
  "last_accessed": 1703030500000,
  "metadata": {
    "topic_tags": ["mathematics", "anxiety", "learning"],
    "personality_influence": ["empathy", "patience"],
    "memory_type": "relationship"
  }
}

memory graph

consolidated memories and their relationships are storied in the memory graph, which can be queried at runtime to make relevant memories available to an agent.

{
  "memories": {
    "mem_01HKG9X5NJWT": {
      // consolidated memory object
    }
  },
  "personality_state": {
    "base_traits": {
      "empathy": 0.8,
      "patience": 0.7,
      "analytical": 0.6
      "last_evolution": 1703030500000
    },
  },
  "indices": {
    "temporal": {
      // time-based index of memories
    },
    "emotional": {
      // emotional valence index
    },
    "semantic": {
      // topic and content-based index
    }
  },
  "stats": {
    "total_memories": 150,
    "last_consolidation": 1703030500000,
  }
}

memory parameters

field	range	description	example
importance	0.0 - 1.0	how significant a memory is for future interactions. higher values increase likelihood of recall.	0.8 = very important memory that should strongly influence future behavior
emotional_valence	-1.0-1.0	the positive/negative emotional charge of a memory fragment	-0.2 = slightly negative emotional experience
insight_type	string	categorizes the type of learning or understanding gained from the interaction	"relationship_development", "user_preference", "learning_style"
emotional_signature.valence	-1.0 - 1.0	overall emotional direction of the consolidated memory	0.3 = moderately positive emotional memory
emotional_signature.intensity	0.0 - 1.0	strength of emotional impact on the agent. higher values mean stronger influence on emotional state.	0.7 = strong emotional impact