Skip to main content
The companion module lives in packages/core/src/companion/.

​
Trust Ladder

Trust governs the companion’s capabilities. It’s stored in companion_settings.trustLevel as an integer 0–4.
LevelNameCapabilities
0WatcherRead-only: observe quests and stats
1AdvisorSuggest actions, create reminders
2ScribeCreate quests, log entries, run read-only tools
3AgentExecute write tools (with user approval prompt)
4SovereignFull autonomy, no approval prompts
Trust changes are logged to trust_log with a timestamp and reason.

​
Companion Settings

Per-user companion settings: 
type CompanionSettings = {
  userId: string;
  provider: "anthropic" | "openai" | "google" | "ollama";
  model: string;
  name: string; // companion's name
  personality: string; // personality description
  trustLevel: 0 | 1 | 2 | 3 | 4;
  focusAreas: string[]; // life domains to emphasize
};
Settings are initialized by createCompanionSettings with sensible defaults. Update via grindxp companion soul.

​
AI Provider Registry

registry.ts resolves the configured provider to a Vercel AI SDK model instance: 
import { resolveProvider } from "@grindxp/core/companion";

const model = resolveProvider(settings);
// → Anthropic / OpenAI / Google / Ollama model instance
Supported providers:
ProviderDefault modelNotes
Anthropicclaude-3-5-haiku-latestAny Anthropic model string accepted
OpenAIgpt-4o-miniAny OpenAI model string accepted
Googlegemini-2.0-flash-expAny Google model string accepted
Ollamallama3.1:8bAny model running at OLLAMA_BASE_URL

​
System Prompt

prompt.ts generates the companion’s system prompt dynamically from:
  • Companion name and personality
  • Trust level capabilities
  • User’s current quest state
  • Active skill tree snapshot
  • Time of day and timezone
The prompt is regenerated on each conversation start to reflect the current state.

​
Context Building

context.ts assembles the context object passed to the agent:
  • User profile (level, XP, timezone)
  • Active quests
  • Quests completed today
  • Best streaks
  • Top skills
  • Recent quest log entries
  • Any pending forge signals
This context is injected into the system prompt and kept updated across the conversation.