useveyra

flowchart LR

A["Unstructured thought"] --> B["Validate input"]

B --> C["Retrieve relevant memories"]

C --> D["Planning provider"]

D --> E["Validated bounded plan"]

E --> F["Focus session"]

F --> G["Progress summary"]

G --> H["Quest and achievement evaluation"]

H -. "reusable learning" .-> C

npm  i  useveyra

import {
  InMemoryMemoryStore,
  InMemoryProgressStore,
  OpenAIEmbeddingProvider,
  OpenAIPlanningProvider,
  Veyra,
} from "useveyra";

const apiKey = process.env.OPENAI_API_KEY;

const model = process.env.VEYRA_OPENAI_MODEL;

if (!apiKey || !model) {
  throw new Error("Set OPENAI_API_KEY and VEYRA_OPENAI_MODEL");
}

const veyra = new Veyra({
  planningProvider: new OpenAIPlanningProvider(apiKey, model),

  embeddingProvider: new OpenAIEmbeddingProvider(
    apiKey,

    process.env.VEYRA_EMBEDDING_MODEL,
  ),

  memoryStore: new InMemoryMemoryStore(),

  progressStore: new InMemoryProgressStore(),
});

const plan = await veyra.plans.create({
  userId: "user_123",

  thought:
    "I need to finish the landing page, answer emails, and prepare tomorrow's launch.",

  availableMinutes: 120,

  energy: "medium",

  maximumTasks: 4,

  timezone: "Asia/Makassar",
});

console.log(plan.summary, plan.tasks, plan.influencedByMemories);

import {
  DeterministicPlanningProvider,
  FixedClock,
  InMemoryMemoryStore,
  InMemoryProgressStore,
  Veyra,
} from "useveyra";

const clock = new FixedClock("2026-01-01T09:00:00.000Z");

let sequence = 0;

const nextId = () => `demo_${++sequence}`;

const veyra = new Veyra({
  planningProvider: new DeterministicPlanningProvider(clock, nextId),

  memoryStore: new InMemoryMemoryStore(),

  progressStore: new InMemoryProgressStore(),

  clock,

  idGenerator: nextId,
});

const plan = await veyra.plans.create({
  userId: "offline_user",

  thought: "Draft the launch post, review it, schedule it",

  availableMinutes: 75,
});

npm  run  example:offline

flowchart TB

subgraph Application["Application boundary"]

API["Veyra facade"]

Browser["Browser client"]

Wallet["Wallet adapter"]

end



subgraph Core["Core SDK"]

Plans["Planning service"]

Memory["Memory and ranking"]

Sessions["Session state machine"]

Progress["Summaries and rewards"]

end



subgraph Adapters["Injected adapters"]

PlanningProvider["PlanningProvider"]

EmbeddingProvider["EmbeddingProvider"]

MemoryStore["MemoryStore"]

ProgressStore["ProgressStore"]

Clock["Clock and ID generator"]

end



subgraph Optional["Optional subpath exports"]

Voice["OpenAI Realtime"]

Solana["Solana identity, proof, payment"]

end



API --> Plans

API --> Memory

API --> Sessions

API --> Progress

Plans --> PlanningProvider

Memory --> EmbeddingProvider

Memory --> MemoryStore

Sessions --> ProgressStore

Sessions --> Clock

Browser --> Voice

Wallet --> Solana

sequenceDiagram

participant App

participant V as Veyra

participant E as EmbeddingProvider

participant M as MemoryStore

participant P as PlanningProvider

participant S as ProgressStore



App->>V: plans.create(input, options)

V->>V: Zod validation

opt Embeddings configured

V->>E: embed(thought)

E-->>V: query vector

V->>M: list(userId)

M-->>V: candidate memories

V->>V: similarity + importance + recency + novelty

end

V->>P: createPlan(input + memory content)

P-->>V: structured Plan

V->>V: validate time bound

V->>S: savePlan(plan)

V-->>App: typed Plan

OPENAI_API_KEY=

VEYRA_OPENAI_MODEL=

VEYRA_EMBEDDING_MODEL=text-embedding-3-small

VEYRA_OPENAI_TIMEOUT_MS=30000

VEYRA_REALTIME_MODEL=

SOLANA_RPC_URL=https://api.devnet.solana.com

SOLANA_CLUSTER=devnet

const plan = await veyra.plans.create(
  {
    userId: "user_123",

    thought: "Review analytics and write the weekly update",

    availableMinutes: 50,

    energy: "low",

    maximumTasks: 3,

    currentTime: new Date().toISOString(),

    timezone: "Europe/Amsterdam",
  },

  { timeoutMs: 30_000, signal: abortController.signal },
);

const preference = await veyra.memory.remember({
  userId: "user_123",

  kind: "preference",

  content: "I prefer writing work before meetings.",

  importance: 0.8,
});

const matches = await veyra.memory.search({
  userId: "user_123",

  query: "When should I schedule writing?",

  limit: 5,

  kinds: ["preference", "habit"],
});

await veyra.memory.update({ id: preference.id, importance: 0.9 });

await veyra.memory.forget({ id: preference.id });

score = similarity × 0.55

+ importance × 0.25

+ recency × 0.15

+ novelty × 0.05

const result = await veyra.memory.extract({
  userId: "user_123",

  text: "I prefer quiet rooms. The weather is nice today.",

  confirmationMode: "suggest",
});

stateDiagram-v2

[*] --> Active: start

Active --> Paused: pause

Paused --> Active: resume

Active --> Completed: complete

Paused --> Completed: complete

Active --> Cancelled: cancel

Paused --> Cancelled: cancel

Completed --> [*]

Cancelled --> [*]

const session = await veyra.sessions.start({
  userId: "user_123",

  planId: plan.id,

  taskId: plan.tasks[0]?.id,

  plannedMinutes: 25,
});

await veyra.sessions.checkIn({
  sessionId: session.id,

  note: "First draft complete",

  progress: 0.6,

  interrupted: false,
});

await veyra.sessions.pause(session.id);

await veyra.sessions.resume(session.id);

const completed = await veyra.sessions.complete({ sessionId: session.id });

const daily = await veyra.summaries.daily({
  userId: "user_123",

  date: "2026-08-04",

  timezone: "Asia/Makassar",
});

const weekly = await veyra.summaries.weekly({
  userId: "user_123",

  start: "2026-08-03T00:00:00.000Z",

  timezone: "Asia/Makassar",
});

const quest = await veyra.quests.fromPlan({ planId: plan.id });

await veyra.quests.completeTask({
  questId: quest.id,

  taskId: plan.tasks[0]!.id,

  verified: true,

  idempotencyKey: `completion:${quest.id}:${plan.tasks[0]!.id}`,
});

const progress = veyra.quests.getProgress({ questId: quest.id });

const streak = await veyra.streaks.get({
  userId: "user_123",

  timezone: "Asia/Makassar",
});

const eligible = await veyra.achievements.evaluate({ userId: "user_123" });

const unlocked = await veyra.achievements.unlock({
  achievementId: eligible[0]!.id,
});

const proof = await veyra.achievements.createProof({
  achievementId: unlocked.id,

  wallet: "A_VALID_SOLANA_WALLET_ADDRESS",

  evidenceHash: "64_HEXADECIMAL_CHARACTERS",
});

sequenceDiagram

participant Browser

participant Backend

participant OpenAI



Browser->>Backend: Request voice session

Backend->>OpenAI: Create ephemeral client secret

OpenAI-->>Backend: Short-lived secret

Backend-->>Browser: VoiceSessionConfig

Browser->>OpenAI: Connect with ephemeral secret

import { OpenAIVoiceProvider } from "useveyra/voice";

const voice = new OpenAIVoiceProvider(
  process.env.OPENAI_API_KEY!,

  process.env.VEYRA_REALTIME_MODEL,
);

const config = await voice.createSessionConfig({
  instructions: "Be concise, calm, and task-focused.",
});

import { consumeVoiceSessionConfig } from "useveyra/voice";

const config = consumeVoiceSessionConfig(await response.json());

import { InMemoryNonceStore } from "useveyra";

import { SolanaIdentityService } from "useveyra/solana";

const identity = new SolanaIdentityService(new InMemoryNonceStore());

const challenge = await identity.createChallenge({
  domain: "app.example.com",

  wallet: walletAddress,

  expiresInSeconds: 300,
});

const result = await identity.verifyChallenge({
  message: challenge.message,

  wallet: walletAddress,

  nonce: challenge.nonce,

  signature: base58Signature,
});

import { SolanaAchievementService } from "useveyra/solana";

const service = new SolanaAchievementService();

const payload = service.createProofPayload({
  wallet: walletAddress,

  achievementId: "first-focus",

  earnedAt: Math.floor(Date.now() / 1000),

  version: 1,

  evidenceHash: sha256Hex,
});

const transaction = service.buildProofTransaction({
  proof: payload,

  programId,
});

import { SolanaPaymentService } from "useveyra/solana";

const payments = new SolanaPaymentService();

const transaction = await payments.buildUsdcTransfer({
  cluster: "devnet",

  rpcUrl: "https://api.devnet.solana.com",

  mint: configuredMint,

  sender: senderWallet,

  recipient: recipientWallet,

  amount: "12.50",

  decimals: 6,
});

import type {
  Plan,
  PlanningProvider,
  PlanningProviderInput,
  RequestOptions,
} from "useveyra";

class RulesPlanningProvider implements PlanningProvider {
  async createPlan(
    input: PlanningProviderInput,

    _options?: RequestOptions,
  ): Promise<Plan> {
    const createdAt = input.currentTime ?? new Date().toISOString();

    return {
      id: crypto.randomUUID(),

      userId: input.userId,

      summary: "One deliberately small next step.",

      tasks: [
        {
          id: crypto.randomUUID(),

          title: input.thought,

          durationMinutes: Math.min(input.availableMinutes ?? 25, 25),

          energy: input.energy ?? "medium",

          priority: "medium",

          reason: "Keep the first action concrete and bounded.",

          status: "pending",
        },
      ],

      totalDurationMinutes: Math.min(input.availableMinutes ?? 25, 25),

      checkInAfterMinutes: 15,

      createdAt,
    };
  }
}

import { VeyraError } from "useveyra";

const controller = new AbortController();

try {
  const plan = await veyra.plans.create(input, {
    signal: controller.signal,

    timeoutMs: 30_000,

    idempotencyKey: "plan:user_123:2026-08-04",
  });
} catch (error) {
  if (error instanceof VeyraError) {
    console.error({ code: error.code, retryable: error.retryable });
  }
}

flowchart LR

Private["Private offchain data\nTasks, memories, habits, blockers"]

Backend["Trusted application backend"]

OpenAI["Configured AI provider"]

Public["Public Solana data\nWallet, achievement ID, time, version, hash"]

Browser["Browser"]



Private --> Backend

Backend -->|"selected planning context"| OpenAI

Backend -->|"ephemeral secret only"| Browser

Backend -->|"unsigned proof payload"| Public

Private -. "never serialized" .-> Public

npm  install

npm  run  format:check

npm  run  lint

npm  run  typecheck

npm  run  test

npm  run  test:coverage

npm  run  build

npm  run  example:offline

npm  pack  --dry-run

npm  login

npm  publish  --access  public