soulscript

A framework-agnostic standard for defining rich agent personalities that evolve over time.

What this repo is, and isn't

This repo contains the WIP spec for soulscript. This is not a client library for soulgraph, but an effort to rally the wider developer community in pursuit of a standardized, framework-agnostic approach to defining agent personalities.

Note

You can run any examples from this repo on the playground at https://soulgra.ph

Navigating the repo

• spec/SPEC.md - core soulscript spec
• examples/ - original & community-sourced examples
• implementations/ - basic example implementations (basic example in spec, standalone coming soon)

A good place to start would be the examples below.

agent	files
marcus_aurelius	agent.soul · memories.json
luce	agent.soul · memories.json
irina	agent.soul · memories.json
fartcoin-maxi	agent.soul · memories.json

Why does this need to exist?

There's plenty of tooling for developers to build the logic layer, or the "hard skills" of their agents. There's none to give them "soft-skills". With soulscript, our goal is to give developers a standardized way to:

• create agents with distinct personalities that persist across platforms

• define how agents think, react, and evolve through interactions

• share and reuse personality specs

• build tools and libraries around a common standard

• share best practices that can emerge from shared implementations

A real-world practical example: personality filters

One challenge we've faced while building soulgraph memory is observing user<>agent interactions through the filter of a given agent's personality. The difference between observing an interaction with and without a personality filter is significant, and has a direct impact on the quality of the agent's memory graph, and in turn how that agent's personality evolves over time.

With filter:

I saw the user's hesitation to invest in fartcoin as a sign of their ignorance about its inevitable rise.

Without filter:

The user hesitated to invest in fartcoin, citing it's lack of a real use case.

Using soulscript, we can safely reconstruct the prompt for each LLM call with the most up-to-date representation of the agent's personality. We can select just the characteristics we need to build that specific personality filter (i.e. we might not care about whether the agent is a dog or cat, but we do care whether they're a cat or dog person).

Soulgraph & soulscript

Soulgraph is a platform, with a token on Solana, that enables developers to add persistent, user-bound memory, real-time comms and other "soft-skills" to their agents without having to set up their own infra.