@elizaos/plugin-scratchpad 2.0.0-alpha

package/README.md

@@ -0,0 +1,161 @@
+# @elizaos/plugin-scratchpad
+
+File-based memory storage plugin for ElizaOS. Provides persistent notes and memories that can be written, read, searched, and managed across sessions.
+
+## Overview
+
+This plugin enables agents to maintain a persistent scratchpad of notes and memories stored as markdown files. It's inspired by the Otto memory-core extension and provides similar functionality adapted for the ElizaOS plugin architecture.
+
+## Features
+
+- **Persistent Storage**: Notes are stored as markdown files that persist across sessions
+- **Semantic Search**: Search through entries by content with relevance scoring
+- **CRUD Operations**: Full support for Create, Read, Update (append), and Delete
+- **Tagging**: Organize entries with tags for better categorization
+- **Provider Integration**: Automatic context about scratchpad state for the agent
+
+## Installation
+
+```bash
+npm install @elizaos/plugin-scratchpad
+```
+
+## Usage
+
+Add the plugin to your agent configuration:
+
+```typescript
+import { scratchpadPlugin } from "@elizaos/plugin-scratchpad";
+
+const agent = {
+  // ... other config
+  plugins: [scratchpadPlugin],
+};
+```
+
+## Actions
+
+### SCRATCHPAD_WRITE
+
+Create a new scratchpad entry.
+
+**Similes**: SAVE_NOTE, CREATE_NOTE, WRITE_NOTE, REMEMBER_THIS, SAVE_MEMORY, JOT_DOWN, NOTE_THIS
+
+**Example**:
+```
+User: "Please save a note about the meeting tomorrow at 3pm with John"
+Agent: "I've saved a note titled 'Meeting with John'. You can retrieve it later."
+```
+
+### SCRATCHPAD_READ
+
+Read the content of a specific scratchpad entry.
+
+**Similes**: GET_NOTE, READ_NOTE, RETRIEVE_NOTE, GET_MEMORY, FETCH_NOTE, OPEN_NOTE
+
+**Example**:
+```
+User: "Show me the note about the meeting"
+Agent: "Here's the note 'Meeting with John': Meeting scheduled for tomorrow at 3pm..."
+```
+
+### SCRATCHPAD_SEARCH
+
+Search through scratchpad entries for relevant information.
+
+**Similes**: FIND_NOTE, SEARCH_NOTES, LOOKUP_MEMORY, FIND_MEMORY, SEARCH_MEMORY, RECALL
+
+**Example**:
+```
+User: "What notes do I have about marketing?"
+Agent: "I found 2 entries mentioning marketing: 1) 'Marketing Strategy' (85% match)..."
+```
+
+### SCRATCHPAD_LIST
+
+List all scratchpad entries with their titles and modification dates.
+
+**Similes**: SHOW_NOTES, LIST_NOTES, ALL_NOTES, MY_NOTES, SHOW_MEMORIES
+
+**Example**:
+```
+User: "Show me all my saved notes"
+Agent: "You have 5 scratchpad entries: 1) Meeting notes (modified today)..."
+```
+
+### SCRATCHPAD_APPEND
+
+Append additional content to an existing scratchpad entry.
+
+**Similes**: ADD_TO_NOTE, UPDATE_NOTE, APPEND_NOTE, EXTEND_NOTE, ADD_MORE
+
+**Example**:
+```
+User: "Add to the meeting notes that we decided on a $50k budget"
+Agent: "I've appended the budget decision to the meeting notes."
+```
+
+### SCRATCHPAD_DELETE
+
+Delete a scratchpad entry by its ID.
+
+**Similes**: REMOVE_NOTE, DELETE_NOTE, FORGET_NOTE, ERASE_NOTE, REMOVE_MEMORY
+
+**Example**:
+```
+User: "Delete the note about the old meeting"
+Agent: "I've deleted the scratchpad entry 'old-meeting'."
+```
+
+## Provider
+
+### scratchpad
+
+Provides information about the user's scratchpad entries to the agent's context. This allows the agent to be aware of saved notes without explicitly querying.
+
+The provider returns:
+- Summary of recent entries (up to 5)
+- Total count of entries
+- Entry IDs and titles
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| SCRATCHPAD_BASE_PATH | string | ~/.eliza/scratchpad | Base directory for scratchpad files |
+| SCRATCHPAD_MAX_FILE_SIZE | number | 1048576 | Maximum file size in bytes (1MB) |
+
+## File Format
+
+Entries are stored as markdown files with YAML frontmatter:
+
+```markdown
+---
+title: "Meeting with John"
+created: 2024-01-15T10:30:00.000Z
+modified: 2024-01-15T10:30:00.000Z
+tags: [meeting, marketing]
+---
+
+Meeting scheduled for tomorrow at 3pm to discuss marketing strategy.
+```
+
+## Development
+
+```bash
+# Build
+bun run build
+
+# Type check
+bun run typecheck
+
+# Lint
+bun run lint
+
+# Test
+bun run test
+```
+
+## License
+
+MIT

package/dist/__tests__/scratchpad-plugin.test.d.ts

@@ -0,0 +1,3 @@
+import type { TestSuite } from "@elizaos/core";
+export declare const ScratchpadPluginE2ETestSuite: TestSuite;
+//# sourceMappingURL=scratchpad-plugin.test.d.ts.map

package/dist/__tests__/scratchpad-plugin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratchpad-plugin.test.d.ts","sourceRoot":"","sources":["../../__tests__/scratchpad-plugin.test.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,eAAe,CAAC;AAG9D,eAAO,MAAM,4BAA4B,EAAE,SAkQ1C,CAAC"}

package/dist/__tests__/scratchpad-service.test.d.ts

@@ -0,0 +1,3 @@
+import type { TestSuite } from "@elizaos/core";
+export declare const ScratchpadServiceTestSuite: TestSuite;
+//# sourceMappingURL=scratchpad-service.test.d.ts.map

package/dist/__tests__/scratchpad-service.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratchpad-service.test.d.ts","sourceRoot":"","sources":["../../__tests__/scratchpad-service.test.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,eAAe,CAAC;AAG9D,eAAO,MAAM,0BAA0B,EAAE,SAgXxC,CAAC"}

package/dist/actions/append.d.ts

@@ -0,0 +1,4 @@
+import { type Action } from "@elizaos/core";
+export declare const scratchpadAppendAction: Action;
+export default scratchpadAppendAction;
+//# sourceMappingURL=append.d.ts.map

package/dist/actions/append.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append.d.ts","sourceRoot":"","sources":["../../actions/append.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAkEvB,eAAO,MAAM,sBAAsB,EAAE,MAgGpC,CAAC;AAEF,eAAe,sBAAsB,CAAC"}

package/dist/actions/delete.d.ts

@@ -0,0 +1,4 @@
+import { type Action } from "@elizaos/core";
+export declare const scratchpadDeleteAction: Action;
+export default scratchpadDeleteAction;
+//# sourceMappingURL=delete.d.ts.map

package/dist/actions/delete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../actions/delete.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAyDvB,eAAO,MAAM,sBAAsB,EAAE,MAuFpC,CAAC;AAEF,eAAe,sBAAsB,CAAC"}

package/dist/actions/list.d.ts

@@ -0,0 +1,4 @@
+import { type Action } from "@elizaos/core";
+export declare const scratchpadListAction: Action;
+export default scratchpadListAction;
+//# sourceMappingURL=list.d.ts.map

package/dist/actions/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../actions/list.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EAOZ,MAAM,eAAe,CAAC;AAMvB,eAAO,MAAM,oBAAoB,EAAE,MAiElC,CAAC;AAEF,eAAe,oBAAoB,CAAC"}

package/dist/actions/read.d.ts

@@ -0,0 +1,4 @@
+import { type Action } from "@elizaos/core";
+export declare const scratchpadReadAction: Action;
+export default scratchpadReadAction;
+//# sourceMappingURL=read.d.ts.map

package/dist/actions/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../actions/read.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAiEvB,eAAO,MAAM,oBAAoB,EAAE,MAoFlC,CAAC;AAEF,eAAe,oBAAoB,CAAC"}

package/dist/actions/search.d.ts

@@ -0,0 +1,4 @@
+import { type Action } from "@elizaos/core";
+export declare const scratchpadSearchAction: Action;
+export default scratchpadSearchAction;
+//# sourceMappingURL=search.d.ts.map

package/dist/actions/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../actions/search.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAsDvB,eAAO,MAAM,sBAAsB,EAAE,MAgFpC,CAAC;AAEF,eAAe,sBAAsB,CAAC"}

package/dist/actions/write.d.ts

@@ -0,0 +1,4 @@
+import { type Action } from "@elizaos/core";
+export declare const scratchpadWriteAction: Action;
+export default scratchpadWriteAction;
+//# sourceMappingURL=write.d.ts.map

package/dist/actions/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../actions/write.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AA6EvB,eAAO,MAAM,qBAAqB,EAAE,MAiEnC,CAAC;AAEF,eAAe,qBAAqB,CAAC"}

package/dist/browser/index.browser.js

@@ -0,0 +1,3 @@
+var b={name:"scratchpad",description:"File-based memory storage (Node.js only - not available in browser).",providers:[],actions:[],async init(){console.warn("[ScratchpadPlugin] This plugin is not available in browser context.")}},m=b;export{b as scratchpadPlugin,m as default};
+
+//# debugId=3B6C58F86231223764756E2164756E21

package/dist/browser/index.browser.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../index.browser.ts"],
+  "sourcesContent": [
+    "/**\n * Browser entry point for plugin-scratchpad\n *\n * Note: The file-based scratchpad functionality is only available in Node.js.\n * This browser entry provides a stub that throws if used in browser context.\n */\nimport type { Plugin } from \"@elizaos/core\";\n\nexport const scratchpadPlugin: Plugin = {\n  name: \"scratchpad\",\n  description: \"File-based memory storage (Node.js only - not available in browser).\",\n\n  providers: [],\n  actions: [],\n\n  async init(): Promise<void> {\n    console.warn(\"[ScratchpadPlugin] This plugin is not available in browser context.\");\n  },\n};\n\nexport default scratchpadPlugin;\n\n// Re-export types for type-checking\nexport type {\n  ScratchpadConfig,\n  ScratchpadEntry,\n  ScratchpadReadOptions,\n  ScratchpadSearchOptions,\n  ScratchpadSearchResult,\n  ScratchpadWriteOptions,\n} from \"./types\";\n"
+  ],
+  "mappings": "AAQO,IAAM,EAA2B,CACtC,KAAM,aACN,YAAa,uEAEb,UAAW,CAAC,EACZ,QAAS,CAAC,OAEJ,KAAI,EAAkB,CAC1B,QAAQ,KAAK,qEAAqE,EAEtF,EAEe",
+  "debugId": "3B6C58F86231223764756E2164756E21",
+  "names": []
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../index';
+export { default } from '../index';

package/dist/build.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+declare const externalDeps: string[];
+declare function build(): Promise<void>;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../build.ts"],"names":[],"mappings":";AAEA,QAAA,MAAM,YAAY,UAAoB,CAAC;AAEvC,iBAAe,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA2FpC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../index';
+export { default } from '../index';