feat(example): python-basic gold — C3.2

Author: jhunterstudio

.env.example

@@ -0,0 +1,2 @@
+SYNAPSE_TOKEN=sk_connect_xxx
+SYNAPSE_BASE_URL=https://forge.synapselayer.org

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Synapse Layer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,53 @@
+# Synapse Layer — Python Basic Example
+
+[![Python 3.9+](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+Store and recall AI agent memories with semantic search in under 30 seconds.
+
+## What this does
+
+This example connects to the Synapse Layer API, stores a memory with semantic
+content, and recalls it using a natural language query. It demonstrates the
+core store/recall loop that gives your AI agents persistent memory across
+sessions and tools.
+
+## Prerequisites
+
+- Python 3.9+
+- A Synapse Layer account and `sk_connect_` token ([get yours here](https://forge.synapselayer.org/dashboard/connect))
+
+## Install
+
+```bash
+git clone https://github.com/SynapseLayer/synapse-layer-python-basic
+cd synapse-layer-python-basic && pip install -r requirements.txt
+cp .env.example .env  # edit with your token
+```
+
+## Run
+
+```bash
+python3 main.py
+```
+
+## Expected output
+
+```
+[store] Saving memory...
+[store] Done.
+
+[recall] Searching for user preferences...
+  [0] content: The user prefers dark mode and communicates in Portuguese.
+      tq_score: 0.716
+
+[recall] 1 memories found.
+```
+
+## Get your token
+
+1. Go to [forge.synapselayer.org](https://forge.synapselayer.org)
+2. Sign up or log in
+3. Navigate to **Dashboard → Connect**
+4. Generate a new `sk_connect_` token
+5. Paste it in your `.env` file

main.py

@@ -0,0 +1,62 @@
+"""Synapse Layer — Python Basic Example
+Store a memory and recall it with semantic search.
+"""
+import os
+import requests
+from dotenv import load_dotenv
+
+load_dotenv()
+
+TOKEN = os.getenv("SYNAPSE_TOKEN", "")
+BASE_URL = os.getenv("SYNAPSE_BASE_URL", "https://forge.synapselayer.org")
+
+if not TOKEN or TOKEN == "sk_connect_xxx":
+    print("ERROR: Set SYNAPSE_TOKEN in .env")
+    print("Get yours at: https://forge.synapselayer.org/dashboard/connect")
+    exit(1)
+
+HEADERS = {"Content-Type": "application/json", "Authorization": f"Bearer {TOKEN}"}
+AGENT = "python-example"
+
+
+def store_memory():
+    """Store a memory via the Forge API."""
+    print("[store] Saving memory...")
+    resp = requests.post(f"{BASE_URL}/api/forge", headers=HEADERS, json={
+        "action": "store",
+        "agent": AGENT,
+        "content": "The user prefers dark mode and communicates in Portuguese.",
+        "intent": "user_preference",
+    })
+    resp.raise_for_status()
+    print("[store] Done.\n")
+
+
+def recall_memory():
+    """Recall memories with a semantic query (cross-agent)."""
+    print("[recall] Searching for user preferences...")
+    resp = requests.post(f"{BASE_URL}/api/forge", headers=HEADERS, json={
+        "action": "recall",
+        "query": "What are the user preferences?",
+        "topK": 5,
+    })
+    resp.raise_for_status()
+    data = resp.json()
+    memories = data.get("memories", [])
+    if memories:
+        for i, mem in enumerate(memories):
+            print(f"  [{i}] content: {mem.get('content', 'N/A')}")
+            print(f"      tq_score: {mem.get('trustQuotient', 'N/A')}")
+        print(f"\n[recall] {len(memories)} memories found.")
+    else:
+        print("[recall] No memories found yet.")
+
+
+if __name__ == "__main__":
+    try:
+        store_memory()
+        recall_memory()
+    except requests.exceptions.HTTPError as e:
+        print(f"API Error: {e.response.status_code} — {e.response.text[:200]}")
+    except Exception as e:
+        print(f"Error: {e}")

requirements.txt

@@ -0,0 +1,2 @@
+requests==2.33.1
+python-dotenv==1.0.1