@positronic/template-new-project 0.0.68 → 0.0.70

package/index.js

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

package/package.json

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

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

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

package/template/.positronic/wrangler.jsonc

@@ -17,6 +17,10 @@
     {
       "tag": "v2",
       "new_sqlite_classes": ["GovernorDO"]
+    },
+    {
+      "tag": "v3",
+      "new_sqlite_classes": ["AuthDO"]
     }
   ],
   "durable_objects": {
@@ -24,7 +28,8 @@
       { "name": "BRAIN_RUNNER_DO", "class_name": "BrainRunnerDO" },
       { "name": "MONITOR_DO", "class_name": "MonitorDO" },
       { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" },
-      { "name": "GOVERNOR_DO", "class_name": "GovernorDO" }
+      { "name": "GOVERNOR_DO", "class_name": "GovernorDO" },
+      { "name": "AUTH_DO", "class_name": "AuthDO" }
     ]
   },
   "r2_buckets": [
@@ -65,7 +70,8 @@
           { "name": "BRAIN_RUNNER_DO", "class_name": "BrainRunnerDO" },
           { "name": "MONITOR_DO", "class_name": "MonitorDO" },
           { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" },
-          { "name": "GOVERNOR_DO", "class_name": "GovernorDO" }
+          { "name": "GOVERNOR_DO", "class_name": "GovernorDO" },
+          { "name": "AUTH_DO", "class_name": "AuthDO" }
         ]
       },
       "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/docs/brain-dsl-guide.md

@@ -642,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:
@@ -669,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
 

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`