Penfield Memory for Clawdbot (clawdbot-penfield)


Persistent, searchable memory for Clawdbot.

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, 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

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
- OAuth Device Code Flow: Secure authentication following RFC 8628
- 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
- Context Management: Save and restore memory checkpoints

Installation

`bash
clawdbot plugins install clawdbot-penfield
`

$3

`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.

Authentication

The plugin uses OAuth 2.0 Device Code Flow (RFC 8628) with automatic token refresh.

$3

`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

$3

`json
{
"version": 1,
"clientId": "dyn_abc123...",
"access": "eyJ...",
"refresh": "eyJ...",
"expires": 1234567890000,
"createdAt": 1234567890000
}
`

Location: ~/.clawdbot/extensions/clawdbot-penfield/credentials.json
File permissions: 0o600 (owner-only read/write)

Available Tools

$3

#### 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

$3

#### 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

$3

#### 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)

$3

#### 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"

$3

#### 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

$3

#### penfield_awaken
Load personality configuration and identity core memories.

Parameters: None

Usage Examples

$3

`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
});
`

$3

`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
});
`

$3

`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

$3

`bash
npm install
`

$3

`bash
npm run typecheck
`

$3

`bash
npm run lint
npm run lint:fix
`

$3

`bash
npm run format
npm run format:check
`

$3

`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