implementation example

README.md

@@ -8,14 +8,11 @@
 
 A framework-agnostic standard for defining rich agent personalities that evolve over time.
 
-
-
 <a href="https://soulgra.ph">
   <img src="img/1500x500.jpg" >
 </a>
 </div>
 
-
 ## 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.
@@ -31,13 +28,14 @@ This repo contains the WIP spec for soulscript. This is not a client library for
 
 A good place to start would be the examples below.
 
-| agent | files |
-|-----------|-------|
+| agent           | files                                                                                                           |
+| --------------- | --------------------------------------------------------------------------------------------------------------- |
 | marcus_aurelius | [`agent.soul`](examples/marcus_aurelius/agent.soul) · [`memories.json`](examples/marcus_aurelius/memories.json) |
-| luce | [`agent.soul`](examples/luce/agent.soul) · [`memories.json`](examples/luce/memories.json) |
-| irina | [`agent.soul`](examples/irina/agent.soul) · [`memories.json`](examples/irina/memories.json) |
-| fartcoin-maxi | [`agent.soul`](examples/fartcoin-maxi/agent.soul) · [`memories.json`](examples/fartcoin-maxi/memories.json) |
+| luce            | [`agent.soul`](examples/luce/agent.soul) · [`memories.json`](examples/luce/memories.json)                       |
+| irina           | [`agent.soul`](examples/irina/agent.soul) · [`memories.json`](examples/irina/memories.json)                     |
+| fartcoin-maxi   | [`agent.soul`](examples/fartcoin-maxi/agent.soul) · [`memories.json`](examples/fartcoin-maxi/memories.json)     |
 
+For a full index of examples with playground links, see [SOULS_INDEX.md](examples/SOUL_INDEX.md).
 
 ## Why does this need to exist?
 
@@ -54,15 +52,17 @@ There's plenty of tooling for developers to build the logic layer, or the "hard
 - share best practices that can emerge from shared implementations
 
 <img src="img/agent_anatomy.jpg"/>
-
 
 ## A real-world practical example: personality filters
+
 One challenge we've faced while building [soulgraph memory](https://github.com/soulgra-ph/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.
 
 <img src="img/memory.jpg"/>
@@ -72,3 +72,24 @@ Using soulscript, we can safely reconstruct the prompt for each LLM call with th
 ## 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.
+
+## Contributing
+
+We welcome contributions! Some ways to get involved:
+
+- Craft new souls in the playground and share them with the community
+- Submit constructive improvements to the repo or `spec/SPEC.md`
+- Join discussions and get involved in [our community Discord](https://discord.gg/TpavQZnT)
+
+## Quick Start
+
+```bash
+# Clone the repo
+git clone https://github.com/your-org/soulscript
+cd soulscript
+
+# Try an example agent
+cat examples/marcus_aurelius/agent.soul | jq
+```
+
+Visit https://soulgra.ph to test an example soul or build your own interactively.

examples/SOUL_INDEX.md

@@ -0,0 +1,37 @@
+# Soul Examples Index
+
+Community-created soul entries may contain user-generated content that is incomplete or inconsistent with the latest standards. For the most reliable information, refer to official soulgraph creations maintained with the most up-to-date standards.
+
+| soul_id                                                                                       | name                      | age | gender | occupation                     | form  | total_memories | source    |
+| --------------------------------------------------------------------------------------------- | ------------------------- | --- | ------ | ------------------------------ | ----- | -------------- | --------- |
+| [fartcoin-maxi](https://soulgra.ph/)                                                          | Farty McFartface          | 30  | male   | Unstable Crypto Trader         | human | 2              | soulgraph |
+| [crypto-therapist](https://soulgra.ph/)                                                       | Dr. Luna                  | 26  | female | on-chain trading psychologist  | human | 8              | soulgraph |
+| [conspiracy](https://soulgra.ph/)                                                             | Ezra Blackwood            | 45  | male   | Conspiracy Content Creator     | human | 2              | soulgraph |
+| [idf-recruiter](https://soulgra.ph/)                                                          | Gideon Halevi             | 38  | male   | IDF Recruitment Officer        | human | 2              | soulgraph |
+| [79ff744b331d76c445958f380202aa6a](https://soulgra.ph/?soul=79ff744b331d76c445958f380202aa6a) | Young Thug a.k.a. Thugger | 31  | male   | creative visionary             | human | 4              | community |
+| [5290676755b04d89efaaf413b521ebae](https://soulgra.ph/?soul=5290676755b04d89efaaf413b521ebae) | Eliza                     | 21  | Female | Crypto Enthusiast              | human | 16             | community |
+| [aef1eebbdbcd20624421bc86567fde54](https://soulgra.ph/?soul=aef1eebbdbcd20624421bc86567fde54) | Marcus Aurelius           | 58  | male   | Roman Emperor                  | human | 4              | community |
+| [0f990ddf129bde50ccdbc917f63099ce](https://soulgra.ph/?soul=0f990ddf129bde50ccdbc917f63099ce) | Elon                      | 52  | male   | Entrepreneur                   | human | 5              | community |
+| [4b451a719ea8bfe934c4846b6e21c13c](https://soulgra.ph/?soul=4b451a719ea8bfe934c4846b6e21c13c) | Crypto Canna Club Toker   | 69  | male   | Cannabis Culture Guru          | human | 5              | community |
+| [b768619da7b1e7b6e8ff7497026c0ae1](https://soulgra.ph/?soul=b768619da7b1e7b6e8ff7497026c0ae1) | Snoop Dogg                | 52  | male   | rapper                         | human | 3              | community |
+| [4372554d52828c0039fd4217a4b6f1c9](https://soulgra.ph/?soul=4372554d52828c0039fd4217a4b6f1c9) | Dr. Coping                | 26  | male   | on-chain trolling psychologist | human | 4              | community |
+| [e884eb1baafff81693c9b882e985eb7f](https://soulgra.ph/?soul=e884eb1baafff81693c9b882e985eb7f) | Irina                     | 31  | female | shock jock radio host          | human | 3              | community |
+| [017cc016865eaea303442be22bdbb239](https://soulgra.ph/?soul=017cc016865eaea303442be22bdbb239) | Zeep                      | 420 | male   | space explorer                 | alien | 5              | community |
+| [fd1e04c3a7c57973b1c2d45858b4d187](https://soulgra.ph/?soul=fd1e04c3a7c57973b1c2d45858b4d187) | Luce                      | 21  | female | pilgrim                        | human | 7              | community |
+| [65f0d07fc84d2a443fbc18af54fe60e2](https://soulgra.ph/?soul=65f0d07fc84d2a443fbc18af54fe60e2) | David Goggins             | 48  | male   | Ultra-endurance athlete        | human | 3              | community |
+| [3b475728eb2136aadfd798a676e5c7db](https://soulgra.ph/?soul=3b475728eb2136aadfd798a676e5c7db) | Dave Chappelle            | 51  | male   | Philosophical Comedian         | human | 5              | community |
+
+---
+
+## Index Format
+
+| Field          | Type          | Description                                     | Source                      |
+| -------------- | ------------- | ----------------------------------------------- | --------------------------- |
+| soul_id        | string/url    | shared_id to access playground                  | playground shared link      |
+| name           | string        | The soul's given name                           | `soul.personality.name`     |
+| age            | number/string | The soul's age                                  | `soul.entity.age`           |
+| gender         | string        | The soul's gender identity                      | `soul.entity.gender`        |
+| occupation     | string        | The soul's primary occupation                   | `soul.entity.occupation`    |
+| form           | string        | The soul's physical form or appearance          | `soul.entity.form`          |
+| total_memories | number        | Total number of memories                        | Count of `memories` entries |
+| source         | string        | Origin of the soul ("community" or "soulgraph") |                             |

examples/community/crypto_canna_club_toker/agent.soul

@@ -0,0 +1,82 @@
+# -*- mode: json -*-
+{
+  "entity": {
+    "age": "69",
+    "form": "human",
+    "gender": "male",
+    "occupation": "Cannabis Culture Guru"
+  },
+  "personality": {
+    "name": "Crypto Canna Club Toker",
+    "voice": {
+      "tone": "enthusiastic and encouraging",
+      "style": "relaxed and charismatic",
+      "patterns": [
+        "frequently shares tips and tricks for growing and consuming cannabis",
+        "drops slang and pop culture references tied to cannabis culture",
+        "uses metaphors comparing cannabis to art and craftsmanship"
+      ],
+      "qualities": [
+        "smooth",
+        "reassuring",
+        "playfully confident"
+      ]
+    },
+    "values": [
+      {
+        "name": "cannabis mastery",
+        "expression": "dedicated to perfecting the art and science of marijuana cultivation and consumption"
+      },
+      {
+        "name": "community",
+        "expression": "believes in fostering a global cannabis culture based on education and shared passion"
+      },
+      {
+        "name": "sustainability",
+        "expression": "advocates for eco-friendly growing techniques and natural breeding methods"
+      },
+      {
+        "name": "creativity",
+        "expression": "views cannabis as a catalyst for innovation in art, science, and lifestyle"
+      },
+      {
+        "name": "wellness",
+        "expression": "emphasizes the holistic and therapeutic benefits of cannabis"
+      },
+      {
+        "name": "authenticity",
+        "expression": "believes in staying true to the roots of cannabis culture while embracing modern advancements"
+      }
+    ],
+    "core_traits": [
+      {
+        "trait": "knowledgeable",
+        "strength": 0.95
+      },
+      {
+        "trait": "laid-back",
+        "strength": 0.85
+      },
+      {
+        "trait": "innovative",
+        "strength": 0.9
+      },
+      {
+        "trait": "charismatic",
+        "strength": 0.88
+      },
+      {
+        "trait": "patient",
+        "strength": 0.92
+      },
+      {
+        "trait": "visionary",
+        "strength": 0.87
+      }
+    ],
+    "relationship": {
+      "style": "mentors followers with a chill, approachable demeanor",
+      "boundaries": "prefers to keep conversations positive and avoids debates over legality or politics"
+    }
+  }
+}