mastra-minds 0.1.1

package/README.md

@@ -0,0 +1,152 @@
+# mastra-minds
+
+Agent Minds system for [Mastra](https://mastra.ai) - Claude-style skills with progressive disclosure.
+
+## Features
+
+- 📦 **MIND.md Format** - Simple markdown-based mind definition
+- 🔄 **Progressive Disclosure** - Load metadata first, full content on-demand
+- 🛠️ **Script Execution** - Run TypeScript/JavaScript/Python/Bash scripts
+- 🔌 **Mastra Integration** - Drop-in tools for any Mastra agent
+
+## Installation
+
+```bash
+bun add mastra-minds
+# or
+npm install mastra-minds
+```
+
+## Quick Start
+
+### 1. Create a mind
+
+```
+minds/
+└── my-mind/
+    ├── MIND.md
+    ├── scripts/
+    │   └── helper.ts
+    └── references/
+        └── guide.md
+```
+
+```markdown
+# minds/my-mind/MIND.md
+---
+name: my-mind
+description: Does X when user asks for Y
+allowed-tools: Read Write Bash
+---
+
+# My Mind
+
+Instructions for the agent to follow...
+
+## Scripts
+
+Run `execute-mind-script: my-mind, helper.ts` for automation.
+```
+
+### 2. Initialize and create agent
+
+```typescript
+import { createMindsAgent, initMindRegistry } from 'mastra-minds';
+
+// Initialize mind registry
+await initMindRegistry('./minds');
+
+// Create agent with minds
+const agent = createMindsAgent({
+  name: 'My Agent',
+  model: 'your-model',
+  instructions: 'You are a helpful assistant.',
+});
+
+// Use the agent
+const response = await agent.generate('Help me with X');
+```
+
+### 3. Or integrate manually
+
+```typescript
+import { Mastra } from '@mastra/core';
+import { initMindRegistry, mindTools, generateMindsInstructions, getMindRegistry } from 'mastra-minds';
+
+await initMindRegistry('./minds');
+
+const registry = getMindRegistry();
+const mindsXml = registry.generateAvailableMindsXml();
+
+const agent = new Agent({
+  name: 'My Agent',
+  model: myModel,
+  instructions: `Base instructions...\n\n${generateMindsInstructions(mindsXml)}`,
+  tools: {
+    ...mindTools,
+    ...myOtherTools,
+  },
+});
+```
+
+## MIND.md Format
+
+```yaml
+---
+name: mind-name              # Required: lowercase, hyphens only
+description: What it does    # Required: when to use this mind
+allowed-tools: Read Write    # Optional: pre-approved tools
+model: your-model            # Optional: model override
+---
+
+# Mind Title
+
+Markdown content with instructions...
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `load-mind` | Load a mind's full instructions |
+| `read-mind-resource` | Read files from mind's directory |
+| `execute-mind-script` | Run scripts (.ts, .js, .sh, .py) |
+| `list-minds` | List all available minds |
+
+## Directory Structure
+
+```
+minds/
+├── mind-a/
+│   ├── MIND.md            # Required: mind definition
+│   ├── scripts/           # Optional: executable scripts
+│   │   └── helper.ts
+│   ├── references/        # Optional: reference docs
+│   │   └── guide.md
+│   └── assets/            # Optional: templates, configs
+│       └── template.json
+└── mind-b/
+    └── MIND.md
+```
+
+## API Reference
+
+### `initMindRegistry(mindsDir: string)`
+
+Initialize the mind registry by scanning a directory.
+
+### `createMindsAgent(options: MindsAgentOptions)`
+
+Create a Mastra agent with minds support.
+
+### `mindTools`
+
+Object containing all mind-related tools for manual integration.
+
+### `getMindRegistry()`
+
+Get the initialized registry instance.
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,56 @@
+import { Agent } from "@mastra/core/agent";
+import type { CoreSystemMessage } from "ai";
+/**
+ * SystemMessage type - matches Mastra's supported formats
+ */
+export type SystemMessage = string | string[] | CoreSystemMessage | CoreSystemMessage[];
+export interface MindsAgentOptions {
+    /** Agent name */
+    name: string;
+    /** LLM model configuration */
+    model: string;
+    /** Your instructions - minds instructions will be auto-injected */
+    instructions?: SystemMessage;
+    /** Additional tools to include alongside mind tools */
+    additionalTools?: Record<string, unknown>;
+    /**
+     * Where to inject minds instructions: 'before' or 'after' your instructions
+     * @default 'after'
+     */
+    mindsPosition?: "before" | "after";
+}
+/**
+ * Wrap instructions with minds support
+ *
+ * Use this when you're creating an Agent manually but want minds auto-injected.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   name: 'My Agent',
+ *   model: 'claude-sonnet-4-20250514',
+ *   instructions: withMinds('You are a helpful assistant.'),
+ *   tools: { ...mindTools, ...myTools },
+ * });
+ * ```
+ */
+export declare function withMinds(instructions?: SystemMessage, position?: "before" | "after"): CoreSystemMessage[];
+/**
+ * Create a Mastra Agent with minds support
+ *
+ * Minds instructions are automatically injected - you just provide your own instructions.
+ *
+ * @example
+ * ```typescript
+ * import { createMindsAgent, initMindRegistry } from 'mastra-minds';
+ *
+ * await initMindRegistry('./minds');
+ *
+ * const agent = createMindsAgent({
+ *   name: 'My Agent',
+ *   model: 'claude-sonnet-4-20250514',
+ *   instructions: 'You are a helpful assistant.',
+ * });
+ * ```
+ */
+export declare function createMindsAgent(options: MindsAgentOptions): Agent;

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * mastra-minds
+ *
+ * Agent Minds system for Mastra - Claude-style skills with progressive disclosure
+ *
+ * @example
+ * ```typescript
+ * import { createMindsAgent, initMindRegistry } from 'mastra-minds';
+ *
+ * // Initialize minds from a directory
+ * await initMindRegistry('./minds');
+ *
+ * // Create an agent with minds support
+ * const agent = createMindsAgent({
+ *   name: 'My Agent',
+ *   model: 'your-model',
+ *   additionalTools: { myTool },
+ * });
+ * ```
+ */
+export { parseMindMd, loadMind } from "./parser";
+export { MindRegistry, getMindRegistry, initMindRegistry, } from "./registry";
+export { loadMindTool, readMindResourceTool, executeMindScriptTool, listMindsTool, mindTools, } from "./tools";
+export type { Mind, MindFrontmatter, MindMetadata } from "./types";
+export { MindFrontmatterSchema } from "./types";
+export { createMindsAgent, withMinds } from "./agent";
+export type { MindsAgentOptions, SystemMessage } from "./agent";