clawdbot-penfield 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 penfieldlabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,519 @@
+# Penfield Memory for Clawdbot (clawdbot-penfield)
+
+[![npm version](https://img.shields.io/npm/v/clawdbot-penfield.svg)](https://www.npmjs.com/package/clawdbot-penfield)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Persistent, searchable memory for [Clawdbot](https://clawd.bot).**
+
+Your lobster remembers every conversation, learns your preferences, and builds knowledge over time—across all your channels.
+
+## 🦞 What is this?
+
+A Clawdbot plugin that connects your agent to [Penfield](https://penfield.app), giving it:
+
+- **Long-term memory** — Conversations persist forever, not just one session
+- **Semantic search** — "What did I say about the Tokyo trip?" actually works
+- **Knowledge graphs** — Memories connect to memories, building real understanding
+- **Cross-channel recall** — Remember WhatsApp convos from Discord
+
+## 🚀 Quick Start
+
+```bash
+clawdbot plugins install clawdbot-penfield
+```
+
+```bash
+clawdbot penfield login
+```
+
+Tell your Clawdbot to "Awaken with Penfield"
+
+## 🔑 Get Access
+
+Penfield is in **free beta**. Sign up for access:
+
+**👉 [accounts.penfield.app/waitlist](https://accounts.penfield.app/waitlist)**
+
+## Features
+
+Native Clawdbot plugin providing direct integration with Penfield's memory and knowledge graph API. This plugin offers 4-5x performance improvement over the MCP server approach by eliminating the mcporter → MCP → Penfield stack.
+
+- **16 Memory Tools**: Complete 1:1 feature parity with Penfield MCP server
+- **OAuth Device Code Flow**: Secure authentication following RFC 8628
+- **Automatic Token Refresh**: Transparent token management with 240-minute expiry buffer
+- **Hybrid Search**: BM25 + vector + graph search capabilities
+- **Knowledge Graph**: Build and traverse relationships between memories
+- **Context Management**: Save and restore memory checkpoints
+- **Artifact Storage**: Store and retrieve files in Penfield
+- **Reflection & Analysis**: Analyze memory patterns and generate insights
+
+## Installation
+
+```bash
+clawdbot plugins install clawdbot-penfield
+```
+
+### From Source (for contributors)
+
+```bash
+git clone https://github.com/penfieldlabs/clawdbot-penfield.git
+cd clawdbot-penfield
+npm install
+npm run build
+clawdbot plugins install -l .
+```
+
+## Configuration
+
+The plugin is **auto-enabled when loaded**. No configuration required for production use.
+
+**Default URLs (production):**
+- API: `https://api.penfield.app`
+- Auth: `https://auth.penfield.app`
+
+**Override with environment variables (for development):**
+
+```bash
+export PENFIELD_API_URL="https://api-dev.penfield.app"
+export PENFIELD_AUTH_URL="https://auth-dev.penfield.app"
+```
+
+**Or with config in `~/.clawdbot/clawdbot.json`:**
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "penfield": {
+        "enabled": true,
+        "config": {
+          "apiUrl": "https://api-dev.penfield.app",
+          "authUrl": "https://auth-dev.penfield.app"
+        }
+      }
+    }
+  }
+}
+```
+
+## Authentication
+
+The plugin uses OAuth 2.0 Device Code Flow (RFC 8628) with automatic token refresh.
+
+### CLI Login
+
+```bash
+clawdbot penfield login
+```
+
+This will:
+1. Discover OAuth endpoints from the auth server
+2. Register a dynamic client (DCR) if needed
+3. Display a device code for user authentication
+4. Poll for token completion
+
+### Credentials
+
+```json
+{
+  "version": 1,
+  "clientId": "dyn_abc123...",
+  "access": "eyJ...",
+  "refresh": "eyJ...",
+  "expires": 1234567890000,
+  "createdAt": 1234567890000
+}
+```
+
+Location: `~/.clawdbot/extensions/penfield/credentials.json`
+File permissions: `0o600` (owner-only read/write)
+
+## Available Tools
+
+### Memory Management
+
+#### `penfield_store`
+Store a new memory in Penfield.
+
+**Parameters:**
+- `content` (required): Memory content (max 10,000 chars)
+- `memory_type` (optional): Type of memory (default: "fact")
+  - Options: fact, insight, conversation, correction, reference, task, checkpoint, identity_core, personality_trait, relationship, strategy
+- `importance` (optional): Score 0-1 (default: 0.5)
+- `confidence` (optional): Score 0-1 (default: 0.8)
+- `source_type` (optional): Source type (e.g., "direct_input", "conversation")
+- `tags` (optional): Array of tags (max 10)
+
+**Example:**
+```typescript
+{
+  "content": "User prefers TypeScript over JavaScript",
+  "memory_type": "fact",
+  "importance": 0.7,
+  "tags": ["preferences", "programming"]
+}
+```
+
+#### `penfield_recall`
+Hybrid search using BM25 + vector + graph.
+
+**Parameters:**
+- `query` (required): Search query (1-4,000 chars)
+- `limit` (optional): Max results (default: 20, max: 100)
+- `bm25_weight` (optional): Keyword weight (default: 0.4)
+- `vector_weight` (optional): Semantic weight (default: 0.4)
+- `graph_weight` (optional): Relationship weight (default: 0.2)
+- `memory_types` (optional): Filter by types
+- `importance_threshold` (optional): Minimum importance
+- `enable_graph_expansion` (optional): Enable traversal (default: true)
+
+**Example:**
+```typescript
+{
+  "query": "programming preferences",
+  "limit": 10,
+  "vector_weight": 0.5,
+  "bm25_weight": 0.3,
+  "graph_weight": 0.2
+}
+```
+
+#### `penfield_search`
+Semantic search variant (higher vector weight).
+
+**Parameters:**
+- `query` (required): Search query
+- `limit` (optional): Max results
+- `memory_types` (optional): Filter by types
+- `importance_threshold` (optional): Minimum importance
+
+#### `penfield_fetch`
+Get a specific memory by ID.
+
+**Parameters:**
+- `memory_id` (required): Memory ID to fetch
+
+#### `penfield_update_memory`
+Update an existing memory.
+
+**Parameters:**
+- `memory_id` (required): Memory ID to update
+- `content` (optional): Updated content
+- `memory_type` (optional): Updated type
+- `importance` (optional): Updated importance
+- `confidence` (optional): Updated confidence
+- `tags` (optional): Updated tags
+
+### Knowledge Graph
+
+#### `penfield_connect`
+Create a relationship between two memories.
+
+**Parameters:**
+- `from_memory_id` (required): Source memory ID
+- `to_memory_id` (required): Target memory ID
+- `relationship_type` (required): Type of relationship
+  - **Knowledge Evolution**: supersedes, updates, evolution_of
+  - **Evidence & Support**: supports, contradicts, disputes
+  - **Hierarchy & Structure**: parent_of, child_of, sibling_of, composed_of, part_of
+  - **Cause & Prerequisites**: causes, influenced_by, prerequisite_for
+  - **Implementation & Testing**: implements, documents, tests, example_of
+  - **Conversation & Attribution**: responds_to, references, inspired_by
+  - **Sequence & Flow**: follows, precedes
+  - **Dependencies**: depends_on
+- `strength` (optional): Relationship strength 0-1 (default: 0.8)
+
+**Example:**
+```typescript
+{
+  "from_memory_id": "22618318-8d82-49c9-8bb8-1cf3a61b3c75",
+  "to_memory_id": "20413926-2446-4f88-bfd6-749b37969f34",
+  "relationship_type": "supports",
+  "strength": 0.9
+}
+```
+
+#### `penfield_explore`
+Traverse the knowledge graph from a starting memory.
+
+**Parameters:**
+- `start_memory_id` (required): Starting memory ID
+- `max_depth` (optional): Max traversal depth (default: 3, max: 10)
+- `relationship_types` (optional): Filter by relationship types
+- `min_strength` (optional): Minimum relationship strength
+
+### Context Management
+
+#### `penfield_save_context`
+Save a checkpoint of current memory state.
+
+**Parameters:**
+- `memory_ids` (required): Array of memory IDs to save
+- `session_id` (optional): Session identifier
+
+#### `penfield_restore_context`
+Restore a previously saved checkpoint.
+
+**Parameters:**
+- `checkpoint_id` (required): Checkpoint ID to restore
+- `full_restore` (optional): Create new copies of memories instead of referencing existing (default: false)
+- `merge_mode` (optional): How to handle conflicts - "append", "replace", or "smart_merge" (default: "append")
+
+#### `penfield_list_contexts`
+List all saved checkpoints.
+
+**Parameters:**
+- `session_id` (optional): Filter by session ID
+- `limit` (optional): Max results (default: 20, max: 100)
+
+### Analysis
+
+#### `penfield_reflect`
+Analyze memory patterns and generate insights.
+
+**Parameters:**
+- `time_window` (optional): Time window - "1d", "7d", "30d", or "90d" (default: "7d")
+- `focus_areas` (optional): Areas to analyze - "memory_usage", "relationships", "importance", "topics", "patterns"
+- `memory_types` (optional): Filter by memory types - "fact", "insight", "conversation", "correction", "reference", "task", "checkpoint", "identity_core", "personality_trait", "relationship", "strategy"
+
+### Artifact Storage
+
+#### `penfield_save_artifact`
+Save a file artifact to Penfield storage.
+
+**Parameters:**
+- `path` (required): Artifact path (e.g., "/project/file.txt")
+- `content` (required): Artifact content
+- `content_type` (optional): MIME type (default: "text/plain")
+
+#### `penfield_retrieve_artifact`
+Retrieve a file artifact from Penfield storage.
+
+**Parameters:**
+- `path` (required): Artifact path to retrieve
+
+#### `penfield_list_artifacts`
+List artifacts in a directory.
+
+**Parameters:**
+- `prefix` (optional): Directory prefix (e.g., "/project/")
+- `limit` (optional): Max results (default: 100, max: 1000)
+
+#### `penfield_delete_artifact`
+Delete a file artifact from Penfield storage.
+
+**Parameters:**
+- `path` (required): Artifact path to delete
+
+### Personality
+
+#### `penfield_awaken`
+Load personality configuration and identity core memories.
+
+**Parameters:** None
+
+## Usage Examples
+
+### Basic Memory Storage and Retrieval
+
+```typescript
+// Store a memory
+await penfield_store({
+  content: "User prefers dark mode for coding",
+  memory_type: "fact",
+  importance: 0.8,
+  tags: ["preferences", "ui"]
+});
+
+// Recall memories
+const results = await penfield_recall({
+  query: "user interface preferences",
+  limit: 5
+});
+```
+
+### Building Knowledge Graphs
+
+```typescript
+// Store two related memories
+const mem1 = await penfield_store({
+  content: "TypeScript provides static typing",
+  memory_type: "fact"
+});
+
+const mem2 = await penfield_store({
+  content: "Static typing helps catch bugs early",
+  memory_type: "insight"
+});
+
+// Connect them
+await penfield_connect({
+  from_memory_id: mem1.id,
+  to_memory_id: mem2.id,
+  relationship_type: "supports",
+  strength: 0.9
+});
+
+// Explore the graph
+const graph = await penfield_explore({
+  start_memory_id: mem1.id,
+  max_depth: 2
+});
+```
+
+### Context Checkpoints
+
+```typescript
+// Save context
+const checkpoint = await penfield_save_context({
+  memory_ids: ["mem_1", "mem_2", "mem_3"],
+  session_id: "session_123"
+});
+
+// Restore later
+await penfield_restore_context({
+  checkpoint_id: checkpoint.id,
+  full_restore: true
+});
+```
+
+## Development
+
+### Setup
+
+```bash
+npm install
+```
+
+### Type Check
+
+```bash
+npm run typecheck
+```
+
+### Lint
+
+```bash
+npm run lint
+npm run lint:fix
+```
+
+### Format
+
+```bash
+npm run format
+npm run format:check
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+## Architecture
+
+```
+index.ts                     # Plugin entry point and registration
+src/
+├── config.ts                # Zod configuration schema with DEFAULT_AUTH_URL/DEFAULT_API_URL
+├── types.ts                 # TypeScript type definitions (single source)
+├── types/typebox.ts         # Centralized TypeBox exports
+├── auth-service.ts          # Background OAuth token refresh service
+├── api-client.ts            # HTTP client wrapper
+├── runtime.ts               # Runtime factory (receives authService from index.ts)
+├── store.ts                 # Credential file I/O with TOKEN_EXPIRY_BUFFER_MS
+├── cli.ts                   # CLI command registration (penfield login)
+├── device-flow.ts           # RFC 8628 Device Code Flow implementation
+└── tools/
+    ├── index.ts             # Tool registry (16 tools)
+    ├── store.ts             # penfield_store
+    ├── recall.ts            # penfield_recall
+    ├── search.ts            # penfield_search
+    ├── fetch.ts             # penfield_fetch
+    ├── update-memory.ts     # penfield_update_memory
+    ├── connect.ts           # penfield_connect
+    ├── explore.ts           # penfield_explore
+    ├── save-context.ts      # penfield_save_context
+    ├── restore-context.ts   # penfield_restore_context
+    ├── list-contexts.ts     # penfield_list_contexts
+    ├── reflect.ts           # penfield_reflect
+    ├── save-artifact.ts     # penfield_save_artifact
+    ├── retrieve-artifact.ts # penfield_retrieve_artifact
+    ├── list-artifacts.ts    # penfield_list_artifacts
+    ├── delete-artifact.ts   # penfield_delete_artifact
+    └── awaken.ts            # penfield_awaken
+```
+
+## Service Lifecycle
+
+The plugin uses two services registered with Clawdbot:
+
+1. **penfield-auth**: Background token refresh service
+   - Started when plugin loads
+   - Checks token expiry every 60 minutes
+   - Auto-refreshes if within 240-minute buffer
+
+2. **penfield**: Runtime lifecycle service
+   - Manages runtime initialization
+   - Handles cleanup on shutdown
+
+## API Endpoint Mapping
+
+| Tool | Method | Endpoint |
+|------|--------|----------|
+| awaken | GET | /api/v2/personality/awakening |
+| connect | POST | /api/v2/relationships |
+| delete_artifact | DELETE | /api/v2/artifacts |
+| explore | POST | /api/v2/relationships/traverse |
+| fetch | GET | /api/v2/memories/{id} |
+| list_artifacts | GET | /api/v2/artifacts/list |
+| list_contexts | GET | /api/v2/checkpoint |
+| recall | POST | /api/v2/search/hybrid |
+| reflect | POST | /api/v2/analysis/reflect |
+| restore_context | POST | /api/v2/checkpoint/{id}/recall |
+| retrieve_artifact | GET | /api/v2/artifacts |
+| save_artifact | POST | /api/v2/artifacts |
+| save_context | POST | /api/v2/checkpoint/create |
+| search | POST | /api/v2/search/hybrid |
+| store | POST | /api/v2/memories |
+| update_memory | PUT | /api/v2/memories/{id} |
+
+## Error Handling
+
+All tools return errors in a consistent format:
+
+```json
+{
+  "error": "Error message here"
+}
+```
+
+Common errors:
+- **401 Unauthorized**: Token expired or invalid (auto-refreshes)
+- **429 Rate Limited**: Too many requests (includes retry-after header)
+- **500 Internal Server Error**: API error
+
+## Performance
+
+This native plugin provides significant performance improvements over the MCP server approach:
+
+- **4-5x faster**: Direct HTTP calls vs. mcporter → MCP → Penfield
+- **Lower latency**: No intermediate proxy servers
+- **Reduced overhead**: Fewer serialization/deserialization steps
+- **Auto token refresh**: No re-authentication delays
+
+## Security
+
+- Automatic token refresh 240 minutes before expiry
+- RFC 8628 compliant Device Code Flow
+- All API calls use HTTPS
+
+## License
+
+MIT
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/penfieldlabs/clawdbot-penfield/issues

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { type PenfieldConfig } from "./src/config.js";
+import type { ClawdbotPluginApi } from "./src/types.js";
+declare const penfieldPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        parse(value: unknown): PenfieldConfig;
+        uiHints: {
+            enabled: {
+                label: string;
+                help: string;
+            };
+            authUrl: {
+                label: string;
+                help: string;
+            };
+            apiUrl: {
+                label: string;
+                help: string;
+            };
+        };
+    };
+    register(api: ClawdbotPluginApi): void;
+};
+export default penfieldPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0C,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAK9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,QAAA,MAAM,cAAc;;;;;qBAMH,OAAO,GAAG,cAAc;;;;;;;;;;;;;;;;kBAuBzB,iBAAiB;CAkEhC,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,93 @@
+import { DEFAULT_AUTH_URL, PenfieldConfigSchema } from "./src/config.js";
+import { createPenfieldRuntime } from "./src/runtime.js";
+import { registerPenfieldTools } from "./src/tools/index.js";
+import { registerLoginCommand } from "./src/cli.js";
+import { createAuthService } from "./src/auth-service.js";
+const penfieldPlugin = {
+    id: "penfield",
+    name: "Penfield Memory",
+    description: "Native Penfield memory integration with 16 tools for knowledge management",
+    configSchema: {
+        parse(value) {
+            // Handle undefined/null when no config section exists
+            if (value === undefined || value === null) {
+                return {};
+            }
+            return PenfieldConfigSchema.parse(value);
+        },
+        uiHints: {
+            enabled: {
+                label: "Enable Penfield",
+                help: "Enable Penfield memory integration",
+            },
+            authUrl: {
+                label: "Auth URL",
+                help: "Penfield Auth service URL (default: https://auth.penfield.app)",
+            },
+            apiUrl: {
+                label: "API URL",
+                help: "Penfield API URL (default: https://api.penfield.app)",
+            },
+        },
+    },
+    register(api) {
+        const cfg = PenfieldConfigSchema.parse(api.pluginConfig ?? {});
+        const logger = api.logger;
+        // Runtime state - follows voice-call pattern
+        let runtimePromise = null;
+        let runtime = null;
+        // Create auth service (single instance)
+        const authUrl = cfg.authUrl || DEFAULT_AUTH_URL;
+        const authService = createAuthService(api, {
+            authUrl,
+            // clientId loaded from credentials on first login
+        });
+        // Lazy runtime initialization with race condition protection
+        const ensureRuntime = async () => {
+            if (runtime)
+                return runtime;
+            if (!runtimePromise) {
+                runtimePromise = createPenfieldRuntime({
+                    api,
+                    config: cfg,
+                    authService,
+                    logger,
+                });
+            }
+            runtime = await runtimePromise;
+            return runtime;
+        };
+        // Register CLI commands (penfield login)
+        registerLoginCommand(api);
+        // Register background auth service
+        api.registerService({
+            id: "penfield-auth",
+            async start() {
+                await authService.start();
+                logger.info("[penfield-auth] Service started");
+            },
+            async stop() {
+                await authService.stop();
+                logger.info("[penfield-auth] Service stopped");
+            },
+        });
+        // Register all 16 tools
+        registerPenfieldTools(api, ensureRuntime);
+        // Register service for runtime lifecycle
+        api.registerService({
+            id: "penfield",
+            async start() {
+                logger.info("[penfield] Service started");
+            },
+            async stop() {
+                if (runtime) {
+                    await runtime.stop();
+                    runtime = null;
+                    runtimePromise = null;
+                }
+                logger.info("[penfield] Service stopped");
+            },
+        });
+    },
+};
+export default penfieldPlugin;

package/dist/src/api-client.d.ts

@@ -0,0 +1,14 @@
+import type { AuthService } from "./auth-service.js";
+import type { Logger } from "./types.js";
+export declare class PenfieldApiClient {
+    private auth;
+    private apiUrl;
+    private logger?;
+    constructor(auth: AuthService, apiUrl: string, logger?: Logger | undefined);
+    request<T>(method: string, endpoint: string, body?: unknown, queryParams?: Record<string, string>): Promise<T>;
+    get<T>(endpoint: string, queryParams?: Record<string, string>): Promise<T>;
+    post<T>(endpoint: string, body?: unknown): Promise<T>;
+    put<T>(endpoint: string, body?: unknown): Promise<T>;
+    delete<T>(endpoint: string, queryParams?: Record<string, string>): Promise<T>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/src/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM,CAAC;gBAFP,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,YAAA;IAGnB,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,EACd,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,OAAO,CAAC,CAAC,CAAC;IAuCP,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI1E,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrD,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIpD,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAGpF"}