@positronic/template-new-project 0.0.77 → 0.0.78

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

@@ -7,7 +7,7 @@ This guide explains how to test Positronic brains using the testing utilities in
 All test files should be placed in the `tests/` directory at the root of your project. This keeps tests separate from your brain implementations and prevents them from being deployed with your application.
 
 Test files should follow the naming convention `<brain-name>.test.ts`. For example:
-- Brain file: `brains/customer-support.ts`
+- Brain file: `src/brains/customer-support.ts`
 - Test file: `tests/customer-support.test.ts`
 
 ## Testing Philosophy
@@ -25,7 +25,7 @@ Testing brains is about verifying they produce the correct outputs given specifi
 
 ```typescript
 import { createMockClient, runBrainTest } from '../tests/test-utils.js';
-import yourBrain from '../brains/your-brain.js';
+import yourBrain from '../src/brains/your-brain.js';
 
 describe('your-brain', () => {
   it('should process user data and generate a report', async () => {
@@ -193,6 +193,66 @@ it('should use customer data to generate personalized content', async () => {
 });
 ```
 
+### Testing Brains with Plugins
+
+Brains that use plugins (gmail, slack, ntfy, etc.) need mock plugins in tests. **Don't use the project brain wrapper** (`src/brain.ts`) in tests — it has real plugins that need API keys. Instead, use the core `brain()` directly and attach mock plugins:
+
+```typescript
+import { brain, definePlugin } from '@positronic/core';
+import { createMockClient, runBrainTest } from './test-utils.js';
+
+// Create mock plugins that match what the brain expects
+const mockGmail = definePlugin({
+  name: 'gmail',
+  create: () => ({
+    getAccounts: () => [{ name: 'test-account', refreshToken: 'test-token' }],
+    searchThreads: jest.fn().mockResolvedValue([
+      { threadId: 'thread-1' },
+    ]),
+    getThreadDetails: jest.fn().mockResolvedValue({
+      threadId: 'thread-1',
+      subject: 'Test Email',
+      from: 'sender@example.com',
+      body: 'Email body content',
+    }),
+    archiveMessages: jest.fn().mockResolvedValue(undefined),
+  }),
+});
+
+const mockNtfy = definePlugin({
+  name: 'ntfy',
+  create: () => ({
+    send: jest.fn().mockResolvedValue(undefined),
+  }),
+});
+
+// Build the brain directly with mock plugins
+const testBrain = brain('email-processor')
+  .withPlugin(mockGmail)
+  .withPlugin(mockNtfy)
+  .step('Fetch emails', async ({ gmail }) => {
+    const accounts = gmail.getAccounts();
+    const threads = await gmail.searchThreads(accounts[0].refreshToken, 'label:inbox');
+    return { threads };
+  })
+  .step('Notify', async ({ state, ntfy }) => {
+    await ntfy.send(`Found <%= '${state.threads.length}' %> emails`);
+    return state;
+  });
+
+it('should fetch emails and notify', async () => {
+  const mockClient = createMockClient();
+  const result = await runBrainTest(testBrain, { client: mockClient });
+
+  expect(result.completed).toBe(true);
+  expect(result.finalState.threads).toHaveLength(1);
+});
+```
+
+The `name` in `definePlugin` must match what the brain accesses on the step context — `gmail`, `slack`, `ntfy`, etc. The `create()` function returns an object with the same methods the real plugin provides, but backed by mocks.
+
+**Testing brains defined in separate files:** If you're testing an existing brain from `src/brains/`, you can't easily swap its plugins because they come from the project's `createBrain()` call. Instead, re-define the brain's steps in the test with mock plugins (copy the step chain, not the imports). Or restructure so the brain logic is a function that accepts a brain builder.
+
 ## Best Practices
 
 1. **Test Behavior, Not Implementation**
@@ -236,7 +296,7 @@ Following testing best practices, avoid testing:
 
 ```typescript
 import { createMockClient, runBrainTest } from './test-utils.js';
-import analysisBrain from '../brains/analysis-brain.js';
+import analysisBrain from '../src/brains/analysis-brain.js';
 
 describe('analysis-brain', () => {
   it('should analyze customer feedback and generate insights', async () => {

package/template/docs/memory-guide.md

@@ -1,6 +1,6 @@
 # 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.
+This guide covers the memory system in Positronic, which enables brains to store and retrieve long-term memories using [Mem0](https://mem0.ai) via the `mem0` plugin.
 
 ## Overview
 
@@ -8,7 +8,7 @@ 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
+- **Tools for prompt loops** - Built-in tools that let LLMs store and recall memories
 - **Automatic user scoping** - Memories are scoped to the current user via `currentUser`, no manual userId threading needed
 
 ## Quick Start
@@ -19,7 +19,7 @@ The memory system provides:
 npm install @positronic/mem0
 ```
 
-### 2. Set up the provider
+### 2. Set up the API key
 
 Add your Mem0 API key to `.env`:
 
@@ -27,43 +27,53 @@ Add your Mem0 API key to `.env`:
 MEM0_API_KEY=your-api-key-here
 ```
 
-### 3. Configure in brain.ts
+### 3. Add the plugin to your project brain
+
+Configure the mem0 plugin in `src/brain.ts` so all brains get memory:
 
 ```typescript
-import { createBrain, defaultTools } from '@positronic/core';
-import { createMem0Provider, createMem0Tools } from '@positronic/mem0';
+import { createBrain } from '@positronic/core';
+import { mem0 } from '@positronic/mem0';
 import { components } from './components/index.js';
 
-const memory = createMem0Provider({
-  apiKey: process.env.MEM0_API_KEY!,
-});
-
 export const brain = createBrain({
+  plugins: [mem0.setup({ apiKey: process.env.MEM0_API_KEY! })],
   components,
-  defaultTools,
-  memory,
 });
 ```
 
-### 4. Use memory tools in agents
+Or add it to a single brain with `.withPlugin()`:
 
 ```typescript
 import { brain } from '../brain.js';
-import { createMem0Tools } from '@positronic/mem0';
-import { z } from 'zod';
+import { mem0 } from '@positronic/mem0';
 
-const memoryTools = createMem0Tools();
+export default brain('assistant')
+  .withPlugin(mem0.setup({ apiKey: process.env.MEM0_API_KEY! }))
+  .step('Load Context', async ({ mem0: m }) => {
+    const memories = await m.search('user preferences');
+    return { context: memories.map(m => m.content).join('\n') };
+  });
+```
+
+### 4. Use memory tools in prompt loops
+
+```typescript
+import { brain } from '../brain.js';
+import { z } from 'zod';
 
 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,
+  .prompt('Help User', ({ mem0: m }) => ({
+    message: 'The user said: I prefer dark mode',
+    outputSchema: z.object({ result: z.string() }),
+    loop: {
+      tools: {
+        ...m.tools,
+        done: {
+          description: 'Complete the task',
+          inputSchema: z.object({ result: z.string() }),
+          terminal: true,
+        },
       },
     },
   }));
@@ -71,7 +81,7 @@ export default brain('assistant')
 
 ## Memory Tools
 
-The package provides two tools that agents can use:
+The plugin provides two tools on `mem0.tools` that LLMs can call during prompt loops:
 
 ### rememberFact
 
@@ -80,7 +90,7 @@ 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.
+When the LLM calls `rememberFact({ fact: "User prefers dark mode" })`, the fact is stored in Mem0 and can be retrieved later.
 
 ### recallMemories
 
@@ -89,34 +99,26 @@ 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.
+When the LLM calls `recallMemories({ query: "user preferences" })`, it receives matching memories with relevance scores.
 
-### Using Memory Tools in Agents
+### Using Memory Tools in Prompt Loops
 
 ```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,
+  .prompt('Chat', ({ mem0: m }) => ({
+    message: userMessage,
+    outputSchema: z.object({ response: z.string() }),
+    loop: {
+      tools: {
+        ...m.tools,
+        done: {
+          description: 'Send final response',
+          inputSchema: z.object({ response: z.string() }),
+          terminal: true,
+        },
       },
     },
   }));
@@ -124,56 +126,34 @@ Use recallMemories before responding to check for relevant context.`,
 
 ## 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,
-});
-```
+The mem0 plugin includes a built-in adapter that automatically indexes conversations to memory. When a brain completes, the adapter flushes buffered messages to Mem0. This builds up context over time without explicit tool calls.
 
 ### 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 completion**: Flushes buffered messages to memory provider
 - **On error/cancel**: Discards buffer (doesn't store failed conversations)
 
-### Including Tool Calls
+### Disabling Auto-Indexing
 
-By default, tool calls are not included in the indexed conversation. Enable this for full conversation history:
+Auto-indexing is enabled by default. To disable it:
 
 ```typescript
-const adapter = createMem0Adapter({
-  provider,
-  includeToolCalls: true,
-});
+mem0.setup({
+  apiKey: process.env.MEM0_API_KEY!,
+  autoIndex: false,
+})
 ```
 
 ## Accessing Memory in Steps
 
-When memory is attached, you can access it directly in step functions:
+When the mem0 plugin is attached, you can access it directly in step functions via `mem0` on the context. Destructure it as `mem0: m` to avoid shadowing the import:
 
 ### In Regular Steps
 
 ```typescript
 export default brain('my-brain')
-  .step('Load Context', async ({ memory }) => {
-    const memories = await memory.search('user preferences', {
+  .step('Load Context', async ({ mem0: m }) => {
+    const memories = await m.search('user preferences', {
       limit: 5,
     });
 
@@ -183,28 +163,28 @@ export default brain('my-brain')
   });
 ```
 
-### In Agent Config Functions
+### In Prompt Config Functions
 
 ```typescript
 export default brain('my-brain')
-  .brain('Process', async ({ memory }) => {
-    const prefs = await memory.search('user preferences');
+  .prompt('Process', async ({ mem0: m }) => {
+    const prefs = await m.search('user preferences');
 
     const context = prefs.length > 0
       ? '\n\nUser preferences:\n' + prefs.map(p => '- ' + p.content).join('\n')
       : '';
 
     return {
+      message: 'Help the user with their request',
       system: 'You are helpful.' + context,
-      prompt: 'Help the user with their request',
-      tools: { /* ... */ },
+      outputSchema: z.object({ response: z.string() }),
     };
   });
 ```
 
 ## Helper Functions
 
-The package includes helper functions for common memory patterns:
+The package includes helper functions for common memory patterns. These accept any object with `search` and `add` methods, so the `mem0` plugin injection works directly.
 
 ### formatMemories
 
@@ -213,7 +193,7 @@ Formats an array of memories into a readable string:
 ```typescript
 import { formatMemories } from '@positronic/mem0';
 
-const memories = await memory.search('preferences');
+const memories = await m.search('preferences');
 
 const text = formatMemories(memories);
 // "1. User prefers dark mode\n2. User likes concise responses"
@@ -233,9 +213,9 @@ Creates a system prompt augmented with relevant memories:
 import { createMemorySystemPrompt } from '@positronic/mem0';
 
 export default brain('my-brain')
-  .brain('Chat', async ({ memory }) => {
+  .prompt('Chat', async ({ mem0: m }) => {
     const system = await createMemorySystemPrompt(
-      memory,
+      m,
       'You are a helpful assistant.',
       'user context and preferences',
       {
@@ -244,7 +224,11 @@ export default brain('my-brain')
       }
     );
 
-    return { system, prompt: userMessage, tools: { /* ... */ } };
+    return {
+      message: userMessage,
+      system,
+      outputSchema: z.object({ response: z.string() }),
+    };
   });
 ```
 
@@ -255,38 +239,70 @@ Gets just the memory context block for manual prompt construction:
 ```typescript
 import { getMemoryContext } from '@positronic/mem0';
 
-const context = await getMemoryContext(memory, 'user preferences', {
+const context = await getMemoryContext(m, 'user preferences', {
   limit: 5,
 });
 
 const system = 'You are helpful.\n\n' + (context ? '## User Context\n' + context : '');
 ```
 
+## Plugin Configuration
+
+### Required Options
+
+- `apiKey` — your Mem0 API key
+
+### Optional Options
+
+- `scope` — memory scoping mode (see Memory Scoping below)
+  - `'user'` — memories are shared across all brains for each user
+  - `'brain'` — memories are shared across all users for each brain
+  - Default: per-brain-per-user (memories are isolated by both brain and user)
+- `autoIndex` — whether to auto-index conversations on brain completion (default: `true`)
+- `baseUrl` — custom Mem0 API base URL
+- `orgId` — Mem0 organization ID
+- `projectId` — Mem0 project ID
+
+```typescript
+mem0.setup({
+  apiKey: process.env.MEM0_API_KEY!,
+  scope: 'user',
+  autoIndex: false,
+})
+```
+
 ## Memory Scoping
 
-Memories are scoped by two identifiers:
+Memories are scoped by two identifiers that are set automatically:
 
 ### agentId
 
-Automatically set to the brain/step title. Memories are isolated per agent:
+Automatically set to the brain title. Memories are isolated per brain by default:
 
 ```typescript
-brain('support-agent').withMemory(memory)  // agentId = 'support-agent'
-brain('sales-agent').withMemory(memory)    // agentId = 'sales-agent'
+brain('support-agent')    // agentId = 'support-agent'
+  .withPlugin(mem0.setup({ apiKey: '...' }))
+
+brain('sales-agent')      // agentId = 'sales-agent'
+  .withPlugin(mem0.setup({ apiKey: '...' }))
 ```
 
+With `scope: 'user'`, the agentId is cleared so memories are shared across brains for each user.
+
 ### userId
 
 Automatically set from `currentUser.name` 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);
+// userId is auto-bound from currentUser — just use mem0 directly
+await m.search('preferences');
+await m.add([{ role: 'user', content: 'test' }]);
 
-// In tools — the agent just passes the fact/query, userId is automatic
+// In tools — the LLM just passes the fact/query, userId is automatic
 rememberFact({ fact: 'Prefers dark mode' })
 recallMemories({ query: 'preferences' })
 ```
 
+With `scope: 'brain'`, the userId is cleared so memories are shared across users for each brain.
+
 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/plugin-guide.md

@@ -0,0 +1,218 @@
+# Creating Plugins
+
+Plugins let you add services, tools, and event handlers to brains. A plugin bundles everything related to an integration into a single unit.
+
+## Quick Start
+
+```typescript
+// src/plugins/weather.ts
+import { definePlugin } from '@positronic/core';
+import { z } from 'zod';
+
+export const weather = definePlugin({
+  name: 'weather',
+  create: () => ({
+    async forecast(city: string) {
+      const res = await fetch(<%= '\`https://api.weather.com/v1/${city}\`' %>);
+      return res.json();
+    },
+  }),
+});
+```
+
+Use it in a brain:
+
+```typescript
+import { brain } from '../brain.js';
+import { weather } from '../plugins/weather.js';
+
+export default brain('daily-report')
+  .withPlugin(weather)
+  .step('Get Weather', async ({ weather: w }) => {
+    const forecast = await w.forecast('Seattle');
+    return { forecast };
+  });
+```
+
+## Plugin Anatomy
+
+A plugin has three parts:
+
+- **`name`** — identifies the plugin. This is the key on StepContext (e.g., `ctx.weather`).
+- **`setup`** — (optional) defines a config shape. Returns a configured plugin when called.
+- **`create`** — called once per brain run. Returns the plugin's public API.
+
+### Without config
+
+```typescript
+export const myPlugin = definePlugin({
+  name: 'myPlugin',
+  create: () => ({
+    doStuff: () => 'done',
+  }),
+});
+
+// Usage: brain('x').withPlugin(myPlugin)
+// Access: ({ myPlugin }) => myPlugin.doStuff()
+```
+
+### With config
+
+```typescript
+export const slack = definePlugin({
+  name: 'slack',
+  setup: (config: { defaultChannel: string; token: string }) => config,
+  create: ({ config }) => ({
+    async post(channel: string, message: string) {
+      // config.token is available here
+    },
+  }),
+});
+
+// Usage: brain('x').withPlugin(slack.setup({ defaultChannel: '#general', token: '...' }))
+// Access: ({ slack }) => slack.post('#alerts', 'hello')
+```
+
+## What `create` Receives
+
+```typescript
+create: ({ config, brainTitle, currentUser, brainRunId }) => {
+  // config — whatever setup() returned, or undefined
+  // brainTitle — the brain's title string
+  // currentUser — { name: string } of the user running the brain
+  // brainRunId — unique ID for this brain run
+}
+```
+
+Use these to scope your plugin's behavior per brain and user.
+
+## Adding Tools
+
+Tools are functions the LLM can call during prompt loops. Return them under a `tools` key:
+
+```typescript
+export const notes = definePlugin({
+  name: 'notes',
+  create: () => {
+    const saved: string[] = [];
+
+    return {
+      // Service methods — direct access in steps
+      getAll: () => [...saved],
+
+      // Tools — for LLM tool-calling in prompt loops
+      tools: {
+        saveNote: {
+          description: 'Save a note for later',
+          inputSchema: z.object({
+            note: z.string().describe('The note to save'),
+          }),
+          async execute(input: { note: string }) {
+            saved.push(input.note);
+            return { saved: true };
+          },
+        },
+      },
+    };
+  },
+});
+```
+
+Using tools in a prompt loop:
+
+```typescript
+brain('note-taker')
+  .withPlugin(notes)
+  .prompt('Take Notes', ({ notes: n }) => ({
+    message: 'Listen to the user and save important notes',
+    outputSchema: z.object({ summary: z.string() }),
+    loop: {
+      tools: { ...n.tools },
+    },
+  }))
+```
+
+## Adding an Adapter
+
+An adapter receives brain events (START, STEP_COMPLETE, COMPLETE, ERROR, etc.). Use it for logging, indexing, or side effects:
+
+```typescript
+export const analytics = definePlugin({
+  name: 'analytics',
+  setup: (config: { endpoint: string }) => config,
+  create: ({ config, brainTitle }) => ({
+    adapter: {
+      dispatch(event: any) {
+        if (event.type === 'COMPLETE') {
+          fetch(config!.endpoint, {
+            method: 'POST',
+            body: JSON.stringify({ brain: brainTitle, event: 'completed' }),
+          });
+        }
+      },
+    },
+  }),
+});
+```
+
+The adapter is intercepted by the framework — it does NOT appear on StepContext.
+
+## Multiple Plugins
+
+Declare multiple plugins upfront in the `brain()` call:
+
+```typescript
+brain({ title: 'my-brain', plugins: { slack, mem0, analytics } })
+  .step('Go', ({ slack, mem0 }) => {
+    // Both available, fully typed
+  });
+```
+
+Or chain `.withPlugin()` calls:
+
+```typescript
+brain('my-brain')
+  .withPlugin(slack.setup({ token: '...' }))
+  .withPlugin(mem0.setup({ apiKey: '...' }))
+```
+
+## Project-Wide Plugins
+
+Configure plugins once in `src/brain.ts` so all brains get them:
+
+```typescript
+import { createBrain } from '@positronic/core';
+import { components } from './components/index.js';
+import { mem0 } from '@positronic/mem0';
+
+export const brain = createBrain({
+  plugins: [mem0.setup({ apiKey: process.env.MEM0_API_KEY! })],
+  components,
+});
+```
+
+Individual brains can add more plugins with `.withPlugin()`. If a brain calls `.withPlugin()` with a plugin that shares a name with a project-level one, the per-brain config wins.
+
+## Testing Plugins
+
+In tests, create a plugin with mock behavior:
+
+```typescript
+const mockSlack = definePlugin({
+  name: 'slack',
+  create: () => ({
+    post: jest.fn(async () => {}),
+  }),
+});
+
+const testBrain = brain('test')
+  .withPlugin(mockSlack)
+  .step('Notify', async ({ slack }) => {
+    await slack.post('#general', 'hello');
+    return { notified: true };
+  });
+```
+
+## Plugin Scoping
+
+`create()` is called **per brain run** — each run gets a fresh instance. For nested brains (`.brain()` steps), inner brains get their own `create()` call with the inner brain's title and context. This means plugins are automatically scoped per brain.