Quickstart

semantic-loop runs on Deno, a modern TypeScript runtime. If you don't have Deno installed yet:

curl -fsSL https://deno.land/install.sh | sh

Then add the library to your project:

deno add jsr:@semantic-loop/core

This adds @semantic-loop/core to your deno.json import map. You can now import from it in any .ts file.

Let's build a self-improving system from scratch. No database, no API keys, no setup. Everything runs in memory.

What is a "loop"?

A loop is a system that learns from its own output. You give it content, it picks the best item for a situation, the real world tells you how it did, and the next pick is smarter. Repeat forever.

Step 1: Create the loop

import { createLoop } from "@semantic-loop/core";

// "memory" means everything is stored in JavaScript Maps
// — great for learning, no external services needed
const loop = createLoop({ store: "memory" });

createLoop() is the main entry point. It wires up a store (where items live), an embedding provider (optional — turns text into vectors for similarity search), and a critic (scores items after outcomes).

Step 2: Seed content

await loop.seed([
  {
    content: "The moat is the loop that compounds after every post.",
    tribe: "founders",    // audience segment
    kind: "hook",        // content type
  },
  {
    content: "Generic productivity advice.",
    tribe: "founders",
    kind: "hook",
  },
  {
    content: "Why most founders build features when they should build feedback loops.",
    tribe: "founders",
    kind: "hook",
  },
]);

tribe is an audience segment — you can have "founders", "designers", "developers", etc. kind is the content type — "hook", "prompt", "headline", whatever you're optimizing.

IDs and timestamps are generated automatically. If you provide embeddings (vectors), they're stored. If not, the system uses the configured embedding provider (or none, in this case).

Step 3: Select

const pick = await loop.select(undefined, { tribe: "founders" });

console.log(pick.candidate.item.content);
// → one of the three items above

console.log(pick.strategy);
// → "greedy" (best score) or "explore" (random from top pool)

The first argument to select() is a query string (used for semantic similarity when you have embeddings). We pass undefined here because we don't have embeddings yet.

The second argument filters by tribe, kind, etc. The engine uses an epsilon-greedy strategy: most of the time it picks the best item, but sometimes it explores to discover hidden gems.

Step 4: Ingest an outcome

const result = await loop.ingest(pick.candidate.item.id, "instagram", {
  views: 12400,
  likes: 340,
  comments: 45,
  shares: 89,
  saves: 214,
  avgWatchSeconds: 18,
});

console.log(result.finalScore);       // 0.341
console.log(result.critic.rationale);  // why the critic scored it this way
console.log(result.critic.tags);       // ["novelty", "validated"]

ingest() takes an item ID, a platform name (for tracking where outcomes come from), and engagement metrics. It automatically derives an engagement score, runs the critic, and updates the item's aggregate scores.

Step 5: Select again

const next = await loop.select(undefined, { tribe: "founders" });
// → now informed by the outcome — picks what performed

The second select() knows about the first outcome. Items that performed well get higher scores. Items that were never tested get an exploration bonus. This is the compounding loop.

Supabase is a hosted PostgreSQL database with a REST API. It's free to start and handles everything semantic-loop needs: storing items, vector search, and aggregate updates.

Step 1: Create a Supabase project

Go to supabase.com and create a new project. Note your project URL and service role key from Settings > API.

Step 2: Run the migration

Open the SQL Editor in your Supabase dashboard and paste the contents of sql/001_init.sql. This creates three tables and four RPC functions. See the Supabase guide for the full migration with line-by-line explanation.

Step 3: Set environment variables

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-key

Step 4: Change one line

// Before
const loop = createLoop({ store: "memory" });

// After
const loop = createLoop({ store: "supabase" });

When you pass the string "supabase", the library reads SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY from environment variables automatically.

Embeddings turn text into numbers (vectors). When you search for "growth strategies", the system can find items about compounding and moats because they're close together in vector space, even if they don't share the same words.

Without embeddings, every item gets the same similarity score. With embeddings, select("growth strategies") returns items semantically related to that query.

Step 1: Get an OpenAI API key

Sign up at platform.openai.com and create an API key.

Step 2: Set the env var

OPENAI_API_KEY=sk-...

Step 3: Add to config

const loop = createLoop({
  store: "supabase",
  embedding: "openai",  // reads OPENAI_API_KEY from env
});

Now when you call loop.seed(), embeddings are generated automatically for each item. When you call loop.select("growth strategies"), the query is embedded and compared to all items via cosine similarity.

Here's the full picture: Supabase for persistence, OpenAI for semantic search, and tuning options to control how the loop learns.

import { createLoop } from "@semantic-loop/core";

const loop = createLoop({
  store: "supabase",       // durable storage with vector search
  embedding: "openai",     // semantic similarity
  selection: {
    epsilon: 0.2,         // 20% chance of exploring instead of exploiting
  },
  aggregation: {
    decayFactor: 0.9,     // recent outcomes matter more
  },
});

// 1. Seed content with automatic embedding generation
await loop.seed([
  { content: "The moat is the loop that compounds.", tribe: "founders" },
  { content: "Ship fast, learn faster.", tribe: "founders" },
]);

// 2. Select using semantic query — "compounding growth" matches "loop that compounds"
const pick = await loop.select("compounding growth strategies", {
  tribe: "founders",
});

// 3. Use the content in your app, post it, send it...
console.log(pick.candidate.item.content);

// 4. Later, when you have metrics, feed them back
const result = await loop.ingest(pick.candidate.item.id, "twitter", {
  views: 8500,
  likes: 120,
  shares: 34,
  clicks: 210,
});

// 5. Next select() is smarter. The loop compounds.

That's it. Seed content, select the best, observe what happens, feed it back. The system gets smarter with every cycle.