@positronic/template-new-project 0.0.67 → 0.0.69

package/index.js

@@ -53,10 +53,10 @@ module.exports = {
   ],
   setup: async ctx => {
     const devRootPath = process.env.POSITRONIC_LOCAL_PATH;
-    let coreVersion = '^0.0.67';
-    let cloudflareVersion = '^0.0.67';
-    let clientVercelVersion = '^0.0.67';
-    let genUIComponentsVersion = '^0.0.67';
+    let coreVersion = '^0.0.69';
+    let cloudflareVersion = '^0.0.69';
+    let clientVercelVersion = '^0.0.69';
+    let genUIComponentsVersion = '^0.0.69';
 
     // Map backend selection to package names
     const backendPackageMap = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@positronic/template-new-project",
-  "version": "0.0.67",
+  "version": "0.0.69",
   "publishConfig": {
     "access": "public"
   },

package/template/.positronic/src/index.ts

@@ -6,6 +6,7 @@ import {
   BrainRunnerDO,
   MonitorDO,
   ScheduleDO,
+  GovernorDO,
   PositronicManifest,
 } from "@positronic/cloudflare";
 // Import the generated manifests - NOTE the .js extension for runtime compatibility
@@ -37,4 +38,4 @@ export default {
   fetch: app.fetch,
 } satisfies ExportedHandler<Env>;
 
-export { BrainRunnerDO, MonitorDO, ScheduleDO };
+export { BrainRunnerDO, MonitorDO, ScheduleDO, GovernorDO };

package/template/.positronic/wrangler.jsonc

@@ -13,13 +13,18 @@
     {
       "tag": "v1",
       "new_sqlite_classes": ["BrainRunnerDO", "MonitorDO", "ScheduleDO"]
+    },
+    {
+      "tag": "v2",
+      "new_sqlite_classes": ["GovernorDO"]
     }
   ],
   "durable_objects": {
     "bindings": [
       { "name": "BRAIN_RUNNER_DO", "class_name": "BrainRunnerDO" },
       { "name": "MONITOR_DO", "class_name": "MonitorDO" },
-      { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" }
+      { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" },
+      { "name": "GOVERNOR_DO", "class_name": "GovernorDO" }
     ]
   },
   "r2_buckets": [
@@ -59,7 +64,8 @@
         "bindings": [
           { "name": "BRAIN_RUNNER_DO", "class_name": "BrainRunnerDO" },
           { "name": "MONITOR_DO", "class_name": "MonitorDO" },
-          { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" }
+          { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" },
+          { "name": "GOVERNOR_DO", "class_name": "GovernorDO" }
         ]
       },
       "r2_buckets": [

package/template/brain.ts

@@ -81,7 +81,10 @@ import { components } from './components/index.js';
  * const memoryTools = createMem0Tools();
  * ```
  *
- * See docs/memory-guide.md for more details on memory configuration.
+ * Memory is automatically scoped to the current user (via currentUser.id)
+ * and the brain name. No need to pass userId manually.
+ *
+ * See docs/memory-guide.md for full details.
  */
 export const brain = createBrain({
   components,

package/template/brains/example.ts

@@ -7,7 +7,7 @@ const exampleBrain = brain('example')
     topic: 'AI workflows',
   }))
   .step('Generate greeting', async ({ state, client }) => {
-    const result = await client.generateObject({
+    const { object } = await client.generateObject({
       schema: z.object({
         greeting: z.string(),
         funFact: z.string(),
@@ -18,8 +18,8 @@ const exampleBrain = brain('example')
     });
     return {
       ...state,
-      greeting: result.greeting,
-      funFact: result.funFact,
+      greeting: object.greeting,
+      funFact: object.funFact,
     };
   })
   .step('Finish', ({ state }) => ({

package/template/docs/brain-dsl-guide.md

@@ -135,6 +135,41 @@ Key points about prompt steps:
 - You can optionally provide a transform function as the third parameter
 - Type inference works throughout - TypeScript knows about your schema types
 
+#### Per-Step Client Overrides
+
+You can use a different AI model for a specific prompt step by passing a `client` option. This is useful when some steps need a cheaper model for simple tasks and others need a more capable model for complex reasoning:
+
+```typescript
+import { createAnthropicClient } from '@positronic/client-anthropic';
+
+const fastModel = createAnthropicClient({ model: 'claude-haiku-4-5-20251001' });
+const smartModel = createAnthropicClient({ model: 'claude-sonnet-4-5-20250929' });
+
+brain('Multi-Model Brain')
+  .prompt('Quick summary', {
+    template: ({ document }) => `Summarize this briefly: <%= '${document}' %>`,
+    outputSchema: {
+      schema: z.object({ summary: z.string() }),
+      name: 'quickSummary' as const,
+    },
+    client: fastModel,  // Use a fast, cheap model for summarization
+  })
+  .prompt('Deep analysis', {
+    template: ({ quickSummary }) =>
+      `Analyze the implications of this summary: <%= '${quickSummary.summary}' %>`,
+    outputSchema: {
+      schema: z.object({
+        insights: z.array(z.string()),
+        risks: z.array(z.string()),
+      }),
+      name: 'analysis' as const,
+    },
+    client: smartModel,  // Use a more capable model for analysis
+  });
+```
+
+When deployed to Cloudflare, rate limiting is applied automatically to all clients — including per-step overrides — through the Governor system. Brain authors don't need to worry about rate limiting.
+
 ### 3. Nested Brains
 
 Compose complex workflows from smaller brains:
@@ -607,6 +642,101 @@ const brainWithComponents = brain('Custom UI Brain')
   });
 ```
 
+### Typed Store with `withStore()`
+
+The `withStore()` method declares a typed key-value store for persistent structured data. Unlike brain state (which resets each run), store data persists across runs.
+
+#### Declaring Store Shape
+
+Use Zod types to declare the shape of your store. All store keys are scoped per-brain — each brain gets its own namespace automatically.
+
+```typescript
+import { z } from 'zod';
+
+const myBrain = brain('email-preferences')
+  .withStore({
+    deselectedThreads: z.array(z.string()),
+    lastProcessedAt: z.number(),
+  })
+  .step('Process', async ({ store }) => {
+    // Typed get — returns the value or undefined if not set
+    const deselected = await store.get('deselectedThreads') ?? [];
+    const lastTime = await store.get('lastProcessedAt');
+
+    // Typed set
+    await store.set('lastProcessedAt', Date.now());
+
+    return { deselected, lastTime };
+  });
+```
+
+#### Per-User Fields
+
+Mark fields as per-user to scope them to the current user. This is useful for user preferences, user-specific state, or any data that should be isolated between users.
+
+```typescript
+const myBrain = brain('dashboard')
+  .withStore({
+    globalConfig: z.object({ theme: z.string() }),           // shared across all users
+    userPreferences: { type: z.object({ darkMode: z.boolean() }), perUser: true },  // per-user
+  })
+  .step('Load Preferences', async ({ store }) => {
+    const config = await store.get('globalConfig');
+    const prefs = await store.get('userPreferences');  // scoped to currentUser automatically
+    return { config, prefs };
+  });
+```
+
+Per-user fields require a `currentUser` to be set when running the brain. If a per-user field is accessed without a current user, an error is thrown.
+
+#### Store Scoping
+
+All store keys are automatically namespaced:
+
+- **Shared fields**: scoped per-brain (e.g., brain "my-brain" key "counter" is isolated from brain "other-brain" key "counter")
+- **Per-user fields**: scoped per-brain AND per-user (each user gets their own value)
+
+There is no global scope — every field belongs to a specific brain.
+
+#### Store Operations
+
+The store provides four operations:
+
+```typescript
+await store.get('key');     // Returns T | undefined
+await store.set('key', value);  // Sets the value
+await store.delete('key');  // Removes the key
+await store.has('key');     // Returns boolean
+```
+
+#### Using with `createBrain()`
+
+You can declare store fields at the project level so all brains share the same store shape:
+
+```typescript
+// brain.ts
+export const brain = createBrain({
+  services: { slack },
+  store: {
+    processedCount: z.number(),
+    userSettings: { type: z.object({ notifications: z.boolean() }), perUser: true },
+  },
+});
+```
+
+Or declare per-brain stores for brain-specific data:
+
+```typescript
+// brains/my-brain.ts
+export default brain('my-brain')
+  .withStore({ counter: z.number() })
+  .step('Increment', async ({ store }) => {
+    const count = await store.get('counter') ?? 0;
+    await store.set('counter', count + 1);
+    return { count: count + 1 };
+  });
+```
+
 ### Using `createBrain()` for Project Configuration
 
 For project-wide configuration, use `createBrain()` in your `brain.ts` file:
@@ -634,11 +764,14 @@ export const brain = createBrain({
       props: z.object({ message: z.string(), type: z.enum(['info', 'warning', 'error']) }),
       render: (props) => `<div class="alert alert-<%= '${props.type}' %>"><%= '${props.message}' %></div>`
     }
+  },
+  store: {
+    processedCount: z.number(),
   }
 });
 ```
 
-All brains created with this factory will have access to the configured services, tools, and components.
+All brains created with this factory will have access to the configured services, tools, components, and store.
 
 ## Running Brains
 
@@ -733,13 +866,31 @@ for await (const event of brain.run({ client })) {
 
 ## Resources
 
-Access loaded resources with type-safe API:
+Resources are files in your project's `/resources` directory that brains can access at runtime. They provide a type-safe way to load text and binary content.
+
+### Adding Resources
+
+Place files in the `/resources` directory:
+
+```
+resources/
+├── config.json
+├── prompts/
+│   ├── customerSupport.md
+│   └── codeReview.md
+└── data/
+    └── records.csv
+```
+
+### Accessing Resources
+
+Access resources using dot notation that matches the file structure:
 
 ```typescript
 brain('Resource Example').step('Load Data', async ({ resources }) => {
-  const config = await resources.config.loadText();
-  const data = await resources.data.records.loadText();
-  return { config: JSON.parse(config), data };
+  const config = await resources.config.load();
+  const template = await resources.prompts.customerSupport.load();
+  return { config: JSON.parse(config), template };
 });
 ```
 
@@ -748,7 +899,7 @@ Resources are also available in prompt templates:
 ```typescript
 brain('Template Example').prompt('Generate Content', {
   template: async (state, resources) => {
-    const template = await resources.prompts.customerSupport.loadText();
+    const template = await resources.prompts.customerSupport.load();
     return template.replace('{{issue}}', state.issue);
   },
   outputSchema: {
@@ -758,6 +909,52 @@ brain('Template Example').prompt('Generate Content', {
 });
 ```
 
+### Resource Methods
+
+Each resource has a single `load()` method that returns the appropriate type:
+
+- `TextResource.load()` - Returns `Promise<string>` (for text files like `.md`, `.json`, `.txt`)
+- `BinaryResource.load()` - Returns `Promise<Buffer>` (for binary files like images)
+
+The resource type is determined automatically based on file content detection when you run `px resources types`.
+
+### File Naming and Property Access
+
+The resource name you use in code must be a valid JavaScript identifier. The system strips file extensions automatically, so `config.json` is accessed as `resources.config`.
+
+**Important**: Resource filenames must be valid JS identifiers (after extension stripping) to be accessible via dot notation. This means:
+
+```
+resources/
+├── myPrompt.md          ✅  → resources.myPrompt.load()
+├── config.json          ✅  → resources.config.load()
+├── reference-material.md  ❌  → "reference-material" has a hyphen, not a valid identifier
+├── referenceMaterial.md   ✅  → resources.referenceMaterial.load()
+```
+
+Use camelCase or single-word names for your resource files. Avoid hyphens, spaces, or other characters that aren't valid in JavaScript identifiers.
+
+You can also access resources by their full filename (including extension) using bracket notation:
+
+```typescript
+const content = await resources['config.json'].load();
+```
+
+### Type Generation
+
+Run `px resources types` to generate a `resources.d.ts` file in your project root. This provides TypeScript type safety for your resources — your editor will autocomplete resource names and flag typos.
+
+The generated types distinguish between `TextResource` and `BinaryResource` based on file content detection, so `load()` returns the correct type (`string` or `Buffer`).
+
+### Path-Based Access
+
+You can also load resources by path string at any level of the resource tree:
+
+```typescript
+const content = await resources.loadText('prompts/customerSupport.md');
+const binary = await resources.loadBinary('images/logo.png');
+```
+
 ## Organizing Complex Prompts
 
 When prompts become more than a sentence or two, extract them into separate files for better maintainability:
@@ -797,7 +994,7 @@ interface FilterPromptState {
 export const aiFilterPrompt = {
   template: async (state: FilterPromptState, resources: Resources) => {
     // Load a prompt template from resources
-    const template = await resources.prompts.hnFilter.loadText();
+    const template = await resources.prompts.hnFilter.load();
 
     // Build the prompt with state data
     const articleList = state.articles
@@ -885,6 +1082,8 @@ brain('Batch Processor')
 - `concurrency: number` - Maximum number of items processed in parallel (default: 10)
 - `error: (item, error) => Response` - Fallback function when a request fails
 
+Batch prompts also support per-step `client` overrides (see Prompt Steps above), so you can use a different model for batch processing.
+
 ### Result Format
 
 The result is stored as an array of `[item, response]` tuples, preserving the relationship between each input item and its generated response.
@@ -1373,7 +1572,7 @@ const completeBrain = brain({
   .prompt('Generate Plan', {
     template: async (state, resources) => {
       // Load a template from resources
-      const template = await resources.templates.projectPlan.loadText();
+      const template = await resources.templates.projectPlan.load();
       return template.replace('{{context}}', 'software project');
     },
     outputSchema: {

package/template/docs/memory-guide.md

@@ -0,0 +1,292 @@
+# Memory Guide
+
+This guide covers the memory system in Positronic, which enables brains to store and retrieve long-term memories using [Mem0](https://mem0.ai) or other memory providers.
+
+## Overview
+
+The memory system provides:
+- **Long-term memory storage** - Persist facts, preferences, and context across brain runs
+- **Semantic search** - Retrieve relevant memories based on natural language queries
+- **Automatic conversation indexing** - Optionally store all conversations for later retrieval
+- **Tools for agents** - Built-in tools that let agents store and recall memories
+- **Automatic user scoping** - Memories are scoped to the current user via `currentUser`, no manual userId threading needed
+
+## Quick Start
+
+### 1. Install the package
+
+```bash
+npm install @positronic/mem0
+```
+
+### 2. Set up the provider
+
+Add your Mem0 API key to `.env`:
+
+```bash
+MEM0_API_KEY=your-api-key-here
+```
+
+### 3. Configure in brain.ts
+
+```typescript
+import { createBrain, defaultTools } from '@positronic/core';
+import { createMem0Provider, createMem0Tools } from '@positronic/mem0';
+import { components } from './components/index.js';
+
+const memory = createMem0Provider({
+  apiKey: process.env.MEM0_API_KEY!,
+});
+
+export const brain = createBrain({
+  components,
+  defaultTools,
+  memory,
+});
+```
+
+### 4. Use memory tools in agents
+
+```typescript
+import { brain } from '../brain.js';
+import { createMem0Tools } from '@positronic/mem0';
+import { z } from 'zod';
+
+const memoryTools = createMem0Tools();
+
+export default brain('assistant')
+  .brain('Help User', () => ({
+    system: 'You are helpful. Use rememberFact to store user preferences.',
+    prompt: 'The user said: I prefer dark mode',
+    tools: {
+      ...memoryTools,
+      done: {
+        description: 'Complete the task',
+        inputSchema: z.object({ result: z.string() }),
+        terminal: true,
+      },
+    },
+  }));
+```
+
+## Memory Tools
+
+The package provides two tools that agents can use:
+
+### rememberFact
+
+Stores a fact in long-term memory.
+
+- **Input**: `{ fact: string }`
+- **Output**: `{ remembered: boolean, fact: string }`
+
+When the agent calls `rememberFact({ fact: "User prefers dark mode" })`, the fact is stored in Mem0 and can be retrieved later.
+
+### recallMemories
+
+Searches for relevant memories.
+
+- **Input**: `{ query: string, limit?: number }`
+- **Output**: `{ found: number, memories: Array<{ content: string, relevance?: number }> }`
+
+When the agent calls `recallMemories({ query: "user preferences" })`, it receives matching memories with relevance scores.
+
+### Using Memory Tools in Agents
+
+```typescript
+import { brain } from '../brain.js';
+import { createMem0Tools } from '@positronic/mem0';
+import { z } from 'zod';
+
+const memoryTools = createMem0Tools();
+
+export default brain('personalized-assistant')
+  .brain('Chat', () => ({
+    system: `You are a personalized assistant.
+
+Use rememberFact to store important information about the user:
+- Preferences (theme, communication style, etc.)
+- Context (current projects, goals)
+- Any facts they want you to remember
+
+Use recallMemories before responding to check for relevant context.`,
+    prompt: userMessage,
+    tools: {
+      ...memoryTools,
+      done: {
+        description: 'Send final response',
+        inputSchema: z.object({ response: z.string() }),
+        terminal: true,
+      },
+    },
+  }));
+```
+
+## Automatic Conversation Indexing
+
+The Mem0 adapter automatically stores all agent conversations to memory. This builds up context over time without explicit tool calls.
+
+### Setting Up the Adapter
+
+In your `runner.ts`:
+
+```typescript
+import { BrainRunner } from '@positronic/core';
+import { createMem0Adapter, createMem0Provider } from '@positronic/mem0';
+
+const provider = createMem0Provider({
+  apiKey: process.env.MEM0_API_KEY!,
+});
+
+const adapter = createMem0Adapter({ provider });
+
+export const runner = new BrainRunner({
+  adapters: [adapter],
+  client: myClient,
+});
+```
+
+### Adapter Behavior
+
+- **On agent start**: Buffers the initial prompt as a user message
+- **During execution**: Buffers all user and assistant messages
+- **On completion**: Flushes buffer to memory provider
+- **On error/cancel**: Discards buffer (doesn't store failed conversations)
+
+### Including Tool Calls
+
+By default, tool calls are not included in the indexed conversation. Enable this for full conversation history:
+
+```typescript
+const adapter = createMem0Adapter({
+  provider,
+  includeToolCalls: true,
+});
+```
+
+## Accessing Memory in Steps
+
+When memory is attached, you can access it directly in step functions:
+
+### In Regular Steps
+
+```typescript
+export default brain('my-brain')
+  .step('Load Context', async ({ memory }) => {
+    const memories = await memory.search('user preferences', {
+      limit: 5,
+    });
+
+    return {
+      context: memories.map(m => m.content).join('\n'),
+    };
+  });
+```
+
+### In Agent Config Functions
+
+```typescript
+export default brain('my-brain')
+  .brain('Process', async ({ memory }) => {
+    const prefs = await memory.search('user preferences');
+
+    const context = prefs.length > 0
+      ? '\n\nUser preferences:\n' + prefs.map(p => '- ' + p.content).join('\n')
+      : '';
+
+    return {
+      system: 'You are helpful.' + context,
+      prompt: 'Help the user with their request',
+      tools: { /* ... */ },
+    };
+  });
+```
+
+## Helper Functions
+
+The package includes helper functions for common memory patterns:
+
+### formatMemories
+
+Formats an array of memories into a readable string:
+
+```typescript
+import { formatMemories } from '@positronic/mem0';
+
+const memories = await memory.search('preferences');
+
+const text = formatMemories(memories);
+// "1. User prefers dark mode\n2. User likes concise responses"
+
+const formatted = formatMemories(memories, {
+  header: 'Known preferences:',
+  includeScores: true,
+  emptyText: 'No preferences found',
+});
+```
+
+### createMemorySystemPrompt
+
+Creates a system prompt augmented with relevant memories:
+
+```typescript
+import { createMemorySystemPrompt } from '@positronic/mem0';
+
+export default brain('my-brain')
+  .brain('Chat', async ({ memory }) => {
+    const system = await createMemorySystemPrompt(
+      memory,
+      'You are a helpful assistant.',
+      'user context and preferences',
+      {
+        limit: 10,
+        memoriesHeader: '\n\nUser context:',
+      }
+    );
+
+    return { system, prompt: userMessage, tools: { /* ... */ } };
+  });
+```
+
+### getMemoryContext
+
+Gets just the memory context block for manual prompt construction:
+
+```typescript
+import { getMemoryContext } from '@positronic/mem0';
+
+const context = await getMemoryContext(memory, 'user preferences', {
+  limit: 5,
+});
+
+const system = 'You are helpful.\n\n' + (context ? '## User Context\n' + context : '');
+```
+
+## Memory Scoping
+
+Memories are scoped by two identifiers:
+
+### agentId
+
+Automatically set to the brain/step title. Memories are isolated per agent:
+
+```typescript
+brain('support-agent').withMemory(memory)  // agentId = 'support-agent'
+brain('sales-agent').withMemory(memory)    // agentId = 'sales-agent'
+```
+
+### userId
+
+Automatically set from `currentUser.id` when the brain runs. All memory operations are automatically scoped to the current user — no need to pass userId manually:
+
+```typescript
+// userId is auto-bound from currentUser — just use memory directly
+await memory.search('preferences');
+await memory.add(messages);
+
+// In tools — the agent just passes the fact/query, userId is automatic
+rememberFact({ fact: 'Prefers dark mode' })
+recallMemories({ query: 'preferences' })
+```
+
+See the [currentUser section in positronic-guide.md](positronic-guide.md#currentuser) for how to set the current user when running brains.

package/template/docs/positronic-guide.md

@@ -232,9 +232,60 @@ const api = {
 };
 ```
 
+## currentUser
+
+Every brain run requires a `currentUser` — an object with at least an `id` field that identifies who is running the brain. This identity is used to scope per-user data like memory and store fields.
+
+### How currentUser Gets Set
+
+The way `currentUser` is provided depends on how the brain is running:
+
+**Deployed (Cloudflare / production)**: The backend sets `currentUser` from the authenticated request. When a user hits an API endpoint to start a brain run, the auth middleware determines their identity and passes it through. You don't need to set it manually.
+
+**Local development with `px brain run`**: The CLI passes a default user identity automatically. You don't need to do anything special.
+
+**Local development with `runner.ts`**: When calling `runner.run()` directly, you must pass `currentUser`:
+
+```typescript
+import { runner } from './runner.js';
+import myBrain from './brains/my-brain.js';
+
+await runner.run(myBrain, {
+  currentUser: { id: 'local-dev-user' },
+});
+```
+
+**In tests**: Pass `currentUser` when running the brain:
+
+```typescript
+const events = await collectEvents(
+  testBrain.run({
+    client: mockClient,
+    currentUser: { id: 'test-user' },
+  })
+);
+```
+
+### What currentUser Scopes
+
+- **Memory**: All memory operations (search, add) are automatically scoped to the current user. No need to pass `userId` manually — see [docs/memory-guide.md](memory-guide.md).
+- **Store (per-user fields)**: Store fields marked with `perUser: true` are automatically scoped to the current user — see [docs/brain-dsl-guide.md](brain-dsl-guide.md).
+
+### Accessing currentUser in Steps
+
+`currentUser` is available in step context if you need it:
+
+```typescript
+export default brain('greet')
+  .step('Hello', ({ currentUser }) => ({
+    greeting: 'Hello, user ' + currentUser.id,
+  }));
+```
+
 ## Getting Help
 
 - **Documentation**: https://positronic.dev
 - **CLI Help**: `px --help`
 - **Brain DSL Guide**: `/docs/brain-dsl-guide.md` (includes UI steps for generating forms)
+- **Memory Guide**: `/docs/memory-guide.md`
 - **Testing Guide**: `/docs/brain-testing-guide.md`

package/template/runner.ts

@@ -26,8 +26,10 @@ import { google } from '@ai-sdk/google';
  * The adapter automatically indexes all agent conversations to memory.
  * See docs/memory-guide.md for more details.
  */
+const client = new VercelClient(google('gemini-3-pro-preview'));
+
 export const runner = new BrainRunner({
   adapters: [],
-  client: new VercelClient(google('gemini-3-pro-preview')),
+  client,
   resources: {},
-});
+});