Documentation - Penfield™

Quick Start

Get up and running with Penfield™ in under 5 minutes.

Create an account at portal.penfield.app
Generate an API key from the API Keys page
Exchange your API key for a JWT token (see below)
Start making API calls or set up MCP

MCP Setup

Penfield™ works with any AI that supports MCP.

Open Settings → Connectors
Click Add custom connector
Connector name: Penfield
Remote MCP server URL: https://mcp.penfield.app
Sign in with your Penfield™ account when prompted

Recommended: Native connectors work on Desktop, Mobile, and Web — no extra tooling required.

Run this command in your terminal:

claude mcp add --transport streamable-http --scope user penfield https://mcp.penfield.app

Note: Claude Code connects directly over HTTP — no proxy or mcp-remote needed.

Available Tools

Tool	Description
store	Save a memory with type, tags, and importance
recall	Hybrid search for relevant memories and documents
search	Search with filters (tags, dates, source type)
connect	Link memories with typed relationships
explore	Traverse the knowledge graph from a memory
reflect	Analyze recent memory patterns and topics
save_context	Save cognitive state for agent handoffs
restore_context	Resume from a saved context checkpoint

API Reference

Base URL: https://api.penfield.app/api/v2

All endpoints require a valid JWT token in the Authorization header.

Authentication

The API uses a two-step authentication flow. First, exchange your API key for a JWT token (valid 24 hours), then use the token for all subsequent requests.

Endpoint	Description
POST/auth/token	Exchange API key for JWT token (24h validity)

Step 1 — Exchange API Key for JWT

curl -X POST https://api.penfield.app/api/v2/auth/token \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

// Response
{
  "status": "success",
  "data": {
    "access_token": "eyJhbGc...",
    "token_type": "bearer",
    "expires_in": 86400
  }
}

Step 2 — Use JWT for API Calls

curl -X GET https://api.penfield.app/api/v2/memories \
  -H "Authorization: Bearer $JWT"

Important: Do not include trailing slashes on endpoints. Use /memories not /memories/.

Memories

Create, retrieve, update, and delete memories. Memories are automatically embedded for semantic search.

Endpoint	Description
POST/memories	Create a new memory
GET/memories	List memories (paginated)
GET/memories/{id}	Get a specific memory
PUT/memories/{id}	Update a memory
DELETE/memories/{id}	Delete a memory
POST/memories/{id}/connect	Connect two memories with a typed relationship

Create a Memory

curl -X POST https://api.penfield.app/api/v2/memories \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The project uses PostgreSQL with pgvector",
    "memory_type": "fact",
    "tags": ["technical", "database"],
    "importance": 0.8
  }'

Memory types: fact, insight, hypothesis, question, answer, correction, strategy

Search

Search across memories and documents using vector similarity, BM25, or hybrid search.

Endpoint	Description
POST/search	Hybrid search (vector + BM25)
POST/search/vector	Vector similarity search only
POST/search/bm25	BM25 keyword search only

Hybrid Search

curl -X POST https://api.penfield.app/api/v2/search \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database architecture decisions",
    "limit": 10,
    "source_type": "memory"
  }'

Documents

Upload documents to make them searchable. Documents are automatically chunked, embedded, and indexed.

Endpoint	Description
POST/documents/upload	Upload a document (multipart form)
GET/documents	List documents
GET/documents/{id}	Get document metadata
GET/documents/{id}/download	Download original document
DELETE/documents/{id}	Delete document and chunks

Upload a Document

curl -X POST https://api.penfield.app/api/v2/documents/upload \
  -H "Authorization: Bearer $JWT" \
  -F "file=@my-document.pdf"

Supported formats: PDF, TXT, Markdown, and other text-based files.

Need Help?

Have questions or need support? Email us at support@penfield.app. Paid plans include priority support with faster response times.