johnalbertini14-glitch Penfield Memory
Persistent memory that compounds. Your agent remembers conversations, learns preferences, connects ideas, and picks up exactly where it left off—across sessions, days, and channels.
Tools
Memory
| Tool | Purpose | When to use |
|---|---|---|
penfield_store |
Save a memory | User shares preferences, you make a discovery, a decision is made, you learn something worth keeping |
penfield_recall |
Hybrid search (BM25 + vector + graph) | Need context before responding, resuming a topic, looking up prior decisions |
penfield_search |
Semantic search (higher vector weight) | Fuzzy concept search when you don't have exact terms |
penfield_fetch |
Get memory by ID | Following up on a specific memory from recall results |
penfield_update_memory |
Edit existing memory | Correcting, adding detail, changing importance or tags |
Knowledge Graph
| Tool | Purpose | When to use |
|---|---|---|
penfield_connect |
Link two memories | New info relates to existing knowledge, building understanding over time |
penfield_explore |
Traverse graph from a memory | Understanding how ideas connect, finding related context |
Context & Analysis
| Tool | Purpose | When to use |
|---|---|---|
penfield_save_context |
Checkpoint a session | Ending substantive work, preparing for handoff to another agent |
penfield_restore_context |
Resume from checkpoint | Picking up where you or another agent left off |
penfield_list_contexts |
List saved checkpoints | Finding previous sessions to resume |
penfield_reflect |
Analyze memory patterns | Session start orientation, finding themes, spotting gaps |
Artifacts
| Tool | Purpose | When to use |
|---|---|---|
penfield_save_artifact |
Store a file | Saving diagrams, notes, code, reference docs |
penfield_retrieve_artifact |
Get a file | Loading previously saved work |
penfield_list_artifacts |
List stored files | Browsing saved artifacts |
penfield_delete_artifact |
Remove a file | Cleaning up outdated artifacts |
Writing Memories That Actually Work
Memory content quality determines whether Penfield is useful or useless. The difference is specificity and context.
Bad — vague, no context, unfindable later:
"User likes Python"
Good — specific, contextual, findable:
"[Preferences] User prefers Python over JavaScript for backend work.
Reason: frustrated by JS callback patterns and lack of type safety.
Values type hints and explicit error handling. Uses FastAPI for APIs."
What makes a memory findable:
- Context prefix in brackets:
[Preferences],[Project: API Redesign],[Investigation: Payment Bug],[Decision] - The "why" behind the "what" — rationale matters more than the fact itself
- Specific details — names, numbers, dates, versions, not vague summaries
- References to related memories — "This builds on [earlier finding about X]" or "Contradicts previous assumption that Y"
Memory Types
Use the correct type. The system uses these for filtering and analysis.
| Type | Use for | Example |
|---|---|---|
fact |
Verified, durable information | "User's company runs Kubernetes on AWS EKS" |
insight |
Patterns or realizations | "Deployment failures correlate with Friday releases" |
correction |
Fixing prior understanding | "CORRECTION: The timeout isn't Redis — it's a hardcoded batch limit" |
conversation |
Session summaries, notable exchanges | "Discussed migration strategy. User leaning toward incremental approach" |
reference |
Source material, citations | "RFC 8628 defines Device Code Flow for OAuth on input-constrained devices" |
task |
Work items, action items | "TODO: Benchmark recall latency after index rebuild" |
strategy |
Approaches, methods, plans | "For user's codebase: always check types.ts first, it's the source of truth" |
checkpoint |
Milestone states | "Project at 80% — auth complete, UI remaining" |
identity_core |
Immutable identity facts | Set via personality config, rarely stored manually |
personality_trait |
Behavioral patterns | Set via personality config, rarely stored manually |
relationship |
Entity connections | "User works with Chad Schultz on cybersecurity content" |
Importance Scores
Use the full range. Not everything is 0.5.
| Score | Meaning | Example |
|---|---|---|
| 0.9–1.0 | Critical — never forget | Architecture decisions, hard-won corrections, core preferences |
| 0.7–0.8 | Important — reference often | Project context, key facts about user's work |
| 0.5–0.6 | Normal — useful context | General preferences, session summaries |
| 0.3–0.4 | Minor — background detail | Tangential facts, low-stakes observations |
| 0.1–0.2 | Trivial — probably don't store | If you're questioning whether to store it, don't |
Connecting Memories
Connections are what make Penfield powerful. An isolated memory is just a note. A connected memory is understanding.
After storing a memory, always ask: What does this relate to? Then connect it.
Relationship Types (24)
Knowledge Evolution: supersedes · updates · evolution_of
Use when understanding changes. "We thought X, now we know Y."
Evidence: supports · contradicts · disputes
Use when new information validates or challenges existing beliefs.
Hierarchy: parent_of · child_of · sibling_of · composed_of · part_of
Use for structural relationships. Topics containing subtopics, systems containing components.
Causation: causes · influenced_by · prerequisite_for
Use for cause-and-effect chains and dependencies.
Implementation: implements · documents · tests · example_of
Use when something demonstrates, describes, or validates something else.
Conversation: responds_to · references · inspired_by
Use for attribution and dialogue threads.
Sequence: follows · precedes
Use for ordered steps in a process or timeline.
Dependencies: depends_on
Use when one thing requires another.
Recall Strategy
Good queries find things. Bad queries return noise.
Tune search weights for your query type:
| Query type | bm25_weight | vector_weight | graph_weight |
|---|---|---|---|
| Exact term lookup ("Twilio auth token") | 0.6 | 0.3 | 0.1 |
| Concept search ("how we handle errors") | 0.2 | 0.6 | 0.2 |
| Connected knowledge ("everything about payments") | 0.2 | 0.3 | 0.5 |
| Default (balanced) | 0.4 | 0.4 | 0.2 |
Filter aggressively:
memory_types: ["correction", "insight"]to find discoveries and correctionsimportance_threshold: 0.7to skip noiseenable_graph_expansion: trueto follow connections (default, usually leave on)
Workflows
User shares a preference
penfield_store({
content: "[Preferences] User wants responses under 3 paragraphs unless complexity demands more. Dislikes bullet points in casual conversation.",
memory_type: "fact",
importance: 0.8,
tags: ["preferences", "communication"]
})
Investigation tracking
// Start
penfield_store({
content: "[Investigation: Deployment Failures] Reports of 500 errors after every Friday deploy. Checking release pipeline, config drift, and traffic patterns.",
memory_type: "task",
importance: 0.7,
tags: ["investigation", "deployment"]
})
// Discovery — connect to the investigation
discovery = penfield_store({
content: "[Investigation: Deployment Failures] INSIGHT: Friday deploys coincide with weekly batch job at 17:00 UTC. Both compete for DB connection pool. Not a deploy issue — it's resource contention.",
memory_type: "insight",
importance: 0.9,
tags: ["investigation", "deployment", "root-cause"]
})
penfield_connect({
from_memory_id: discovery.id,
to_memory_id: initial_report.id,
relationship_type: "responds_to"
})
// Correction — supersede wrong assumption
correction = penfield_store({
content: "[Investigation: Deployment Failures] CORRECTION: Not a CI/CD problem. Friday batch job + deploy = connection pool exhaustion. Fix: stagger batch job to 03:00 UTC.",
memory_type: "correction",
importance: 0.9,
tags: ["investigation", "deployment", "correction"]
})
penfield_connect({
from_memory_id: correction.id,
to_memory_id: initial_report.id,
relationship_type: "supersedes"
})
Session handoff
penfield_save_context({
name: "deployment-investigation-2026-02",
description: "Investigated deployment timeout issues. memory_id: " + discovery.id,
memory_ids: [discovery.id, correction.id, initial_report.id]
})
Next session or different agent:
penfield_restore_context({
name: "deployment-investigation-2026-02"
})
What NOT to Store
- Verbatim conversation transcripts (too verbose, low signal)
- Easily googled facts (use web search instead)
- Ephemeral task state (use working memory)
- Anything the user hasn't consented to store about themselves
- Every minor exchange (be selective — quality over quantity)
Tags
Keep them short, consistent, lowercase. 2–5 per memory.
Good: preferences, architecture, investigation, correction, project-name
Bad: 2026-02-02, important-memory-about-deployment, UserPreferencesForCommunicationStyle
Also Available Outside OpenClaw
The native OpenClaw plugin is the fastest path, but Penfield works with any AI tool anywhere:
Claude Connectors
Name: Penfield
Remote MCP server URL: https://mcp.penfield.app
Claude Code
Claude mcp add --transport http --scope user penfield https://mcp.penfield.app
MCP Server — for Gemini CLI, Cursor, Windsurf, Intent, Perplexity Desktop or any MCP-compatible tool:
{
"mcpServers": {
"penfield": {
"command": "npx",
"args": [
"mcp-remote@latest",
"https://mcp.penfield.app/"
]
}
}
}
API — direct HTTP access at api.penfield.app for custom integrations.
Same memory, same knowledge graph, same account. The plugin is 4-5x faster (no MCP proxy layer), but everything stays in sync regardless of how you connect.
Links
- Plugin: openclaw-penfield on npm
- Source: github.com/penfieldlabs/openclaw-penfield
- Sign up: portal.penfield.app/sign-up
- Website: penfield.app
- X: @penfieldlabs