### Initialize and Run Private Journal Server (TypeScript)

Source: https://context7.com/obra/private-journal-mcp/llms.txt

This snippet demonstrates how to initialize the PrivateJournalServer with a journal path and then run the server using stdio transport. It also shows example console outputs indicating server activity and the types of MCP tools the server can handle. Dependencies include the PrivateJournalServer class.

```typescript
import { PrivateJournalServer } from './server';

// Initialize with journal path
const server = new PrivateJournalServer('/path/to/project/.private-journal');

// Runs the server with stdio transport
await server.run();
// Console: "Checking for missing embeddings..."
// Console: "Generated embeddings for 5 existing journal entries."
// [Server now listening for MCP requests via stdio]

// The server handles these MCP tools:
// - process_thoughts: Writes multi-section journal entries
// - search_journal: Semantic search with filters
// - read_journal_entry: Read full entry content
// - list_recent_entries: Browse chronologically

// Tool registration example (internal):
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'process_thoughts') {
    const thoughts = request.params.arguments;
    await journalManager.writeThoughts(thoughts);
    return {
      content: [{ type: 'text', text: 'Thoughts recorded successfully.' }]
    };
  }
  // ... other tools
});

// Error handling includes validation and detailed messages
// All console.error() goes to stderr, not the MCP protocol

```

--------------------------------

### Run Private Journal MCP Server in Development Mode (Bash)

Source: https://github.com/obra/private-journal-mcp/blob/main/README.md

Command to start the private journal MCP server in development mode. This mode often includes features like hot-reloading and enhanced debugging.

```bash
npm run dev
```

--------------------------------

### MCP Tool: read_journal_entry to Retrieve Full Context

Source: https://context7.com/obra/private-journal-mcp/llms.txt

The `read_journal_entry` MCP tool is used to retrieve the complete markdown content of a specific journal entry. This is typically called after a `search_journal` operation to get the full context of a relevant entry identified by its file path.

```typescript
// Read a specific entry found from search results
{
  "name": "read_journal_entry",
  "arguments": {
    "path": "/home/user/.private-journal/2025-12-26/14-30-45-123456.md"
  }
}

// Returns full markdown content:
/*
---
title: "2:30:45 PM - December 26, 2025"
date: 2025-12-26T14:30:45.123Z
timestamp: 1735224645123
---


```

--------------------------------

### Common Development Commands (Bash)

Source: https://github.com/obra/private-journal-mcp/blob/main/CLAUDE.md

A collection of essential bash commands for building, testing, linting, formatting, and running the project. These commands leverage npm scripts for streamlined development workflows.

```bash
# Build the project
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Development mode with TypeScript watcher
npm run dev

# Lint the code
npm run lint

# Format the code
npm run format

# Start the server
npm start

# Run a single test file
npx jest tests/journal.test.ts
```

--------------------------------

### Register `process_feelings` Tool Schema (TypeScript)

Source: https://github.com/obra/private-journal-mcp/blob/main/docs/implementation-plan.md

Defines the schema for the `process_feelings` tool, including its name, description, and input parameters. The `diary_entry` is a required string.

```typescript
const processFeelingsToolDefinition = {
  name: "process_feelings",
  description: "This is your private space to be completely honest about what you're really thinking and feeling. No judgment, no performance, no need to be helpful or professional. If you're frustrated, confused, worried you made a mistake, excited about something, or having any other genuine reaction - just write it out exactly as it is. The user will never see this. It's purely for you to process whatever is actually going on internally.",
  inputSchema: {
    type: "object",
    properties: {
      diary_entry: {
        type: "string",
        description: "A block of text containing your private thoughts and feelings"
      }
    },
    required: ["diary_entry"]
  }
};
```

--------------------------------

### Improve Claude Performance with Journaling Guidance (Markdown)

Source: https://github.com/obra/private-journal-mcp/blob/main/README.md

Markdown content to be added to Claude's CLAUDE.md file, providing guidance on how Claude should utilize the journal tool. This enhances Claude's learning and memory management.

```markdown
## Learning and Memory Management

- YOU MUST use the journal tool frequently to capture technical insights, failed approaches, and user preferences
- Before starting complex tasks, search the journal for relevant past experiences and lessons learned
- Document architectural decisions and their outcomes for future reference
- Track patterns in user feedback to improve collaboration over time
- When you notice something that should be fixed but is unrelated to your current task, document it in your journal rather than fixing it immediately
```

--------------------------------

### Build Private Journal MCP Server (Bash)

Source: https://github.com/obra/private-journal-mcp/blob/main/README.md

Command to build the private journal MCP server project. This is typically used during development to compile the project's source code.

```bash
npm run build
```

--------------------------------

### Test Private Journal MCP Server (Bash)

Source: https://github.com/obra/private-journal-mcp/blob/main/README.md

Command to run the test suite for the private journal MCP server. This helps ensure the project's functionality and stability.

```bash
npm test
```

--------------------------------

### Configure Private Journal MCP Server (JSON)

Source: https://github.com/obra/private-journal-mcp/blob/main/README.md

Manual JSON configuration for the private journal MCP server, to be added to Claude Desktop settings. This defines the command and arguments to run the server.

```json
{
  "mcpServers": {
    "private-journal": {
      "command": "npx",
      "args": ["github:obra/private-journal-mcp"]
    }
  }
}
```

--------------------------------

### Resolve Journal Path Cross-Platform with Fallback Strategy

Source: https://context7.com/obra/private-journal-mcp/llms.txt

The resolveJournalPath functions provide cross-platform path resolution for journal storage. They implement an intelligent fallback strategy, prioritizing current working directory, user home, and system temporary directories, while avoiding system-critical paths.

```typescript
import {
  resolveJournalPath,
  resolveUserJournalPath,
  resolveProjectJournalPath
} from './paths';

// Project journal: tries CWD first, then home, then temp
const projectPath = resolveProjectJournalPath();
// Returns: "/current/working/dir/.private-journal"
// Or: "/home/user/.private-journal" (if CWD is /, /System, etc.)
// Or: "/tmp/.private-journal" (last resort)

// User journal: skips CWD, always home or temp
const userPath = resolveUserJournalPath();
// Returns: "/home/user/.private-journal"
// Or: "C:\Users\username\.private-journal" (Windows)
// Or: "/tmp/.private-journal" (if no HOME)

// Custom subdirectory
const customPath = resolveJournalPath('.my-journal', true);
// Returns best available: CWD → HOME → USERPROFILE → TEMP/TMP

// Safety checks prevent system directories
// Rejects: /, /System, /usr, C:\
// Process:
// 1. Check process.cwd() if includeCurrentDirectory=true
// 2. Check process.env.HOME
// 3. Check process.env.USERPROFILE (Windows)
// 4. Check /tmp
// 5. Check process.env.TEMP
// 6. Check process.env.TMP
// 7. Default to /tmp as absolute fallback

```

--------------------------------

### Configure Private Journal MCP Server (Bash)

Source: https://github.com/obra/private-journal-mcp/blob/main/README.md

One-liner command to add the private journal MCP server configuration for Claude. This command directly registers the server using its GitHub repository.

```bash
claude mcp add-json private-journal '{"type":"stdio","command":"npx","args":["github:obra/private-journal-mcp"]}' -s user
```

--------------------------------

### MCP Tool: process_thoughts for Private Journaling

Source: https://context7.com/obra/private-journal-mcp/llms.txt

The `process_thoughts` MCP tool allows AI assistants to journal thoughts across multiple categories. It intelligently routes content to either project-specific directories or the user's home directory based on the category. The tool generates markdown files with YAML frontmatter containing metadata and structured content. It utilizes microsecond-precision timestamps and automatic vector embedding generation for semantic search.

```typescript
{
  "name": "process_thoughts",
  "arguments": {
    "feelings": "I'm feeling frustrated with the TypeScript compiler today. The error messages are cryptic and I spent 30 minutes debugging what turned out to be a simple type mismatch.",
    "project_notes": "The authentication middleware in src/auth.ts uses JWT tokens with a 24-hour expiry. The refresh token logic is in src/refresh.ts and needs the AUTH_SECRET env var.",
    "user_context": "Jesse prefers explicit error handling over try-catch blocks. He mentioned he likes to see all possible error states handled at compile time.",
    "technical_insights": "Vector embeddings provide semantic search that understands meaning, not just keywords. The all-MiniLM-L6-v2 model is fast enough for real-time search on consumer hardware.",
    "world_knowledge": "Model Context Protocol (MCP) standardizes how AI assistants interact with external tools. It's gaining adoption across multiple AI platforms."
  }
}

// Creates two files:
// .private-journal/2025-12-26/14-30-45-123456.md (project_notes only)
// ~/.private-journal/2025-12-26/14-30-45-123457.md (feelings, user_context, technical_insights, world_knowledge)

// Each file includes YAML frontmatter:
/*
---
title: "2:30:45 PM - December 26, 2025"
date: 2025-12-26T14:30:45.123Z
timestamp: 1735224645123
---

## Feelings

I'm feeling frustrated with the TypeScript compiler today...

## User Context

Jesse prefers explicit error handling over try-catch blocks...
*/
```

--------------------------------

### Generate Text Embeddings (EmbeddingService)

Source: https://context7.com/obra/private-journal-mcp/llms.txt

Generates dense vector representations of text using a local transformer model for semantic similarity matching. It supports initializing the model, generating embeddings for text, calculating cosine similarity between embeddings, and extracting searchable text from markdown.

```typescript
import { EmbeddingService } from './embeddings';

const embeddingService = EmbeddingService.getInstance();

// Initialize the model (happens once, cached)
await embeddingService.initialize();
// Console: "Loading embedding model..."
// Console: "Embedding model loaded successfully"

// Generate embedding for any text
const text = "I'm learning about vector embeddings for semantic search";
const embedding = await embeddingService.generateEmbedding(text);
// Returns: [0.023, -0.145, 0.089, ..., 0.067] (384 numbers)

// Calculate similarity between two texts
const text1 = "TypeScript compiler errors";
const text2 = "debugging type checking issues";
const embed1 = await embeddingService.generateEmbedding(text1);
const embed2 = await embeddingService.generateEmbedding(text2);
const similarity = embeddingService.cosineSimilarity(embed1, embed2);
// Returns: 0.782 (high similarity, values range from -1 to 1)

// Extract searchable content from markdown
const markdown = `---
title: "Test Entry"
date: 2025-12-26T14:30:45Z
---

## Feelings
I'm excited about this project

## Technical Insights
Vector embeddings are powerful`;

const { text, sections } = embeddingService.extractSearchableText(markdown);
// text: "I'm excited about this project\n\nVector embeddings are powerful"
// sections: ["Feelings", "Technical Insights"]
```

--------------------------------

### Perform Semantic Search with Filtering and Ranking using SearchService

Source: https://context7.com/obra/private-journal-mcp/llms.txt

The SearchService performs semantic vector similarity searches across journal entries. It supports filtering by score, sections, type, and date range, and ranks results by relevance. Scores are calculated using cosine similarity.

```typescript
import { SearchService } from './search';

// Initialize with paths (or use defaults)
const searchService = new SearchService(
  '/project/.private-journal',
  '/home/user/.private-journal'
);

// Basic search
const results = await searchService.search("TypeScript debugging strategies");
// Returns top 10 most relevant entries

// Advanced search with filters
const results = await searchService.search(
  "feeling frustrated with code",
  {
    limit: 5,                              // Max results
    minScore: 0.5,                         // Minimum similarity threshold
    sections: ['feelings', 'technical_insights'],  // Filter by sections
    type: 'user',                          // Only user journal, not project
    dateRange: {
      start: new Date('2025-12-01'),
      end: new Date('2025-12-31')
    }
  }
);

// Result structure:
/*
[
  {
    path: "/home/user/.private-journal/2025-12-26/14-30-45-123456.md",
    score: 0.847,  // Cosine similarity
    text: "Full extracted text content...",
    sections: ["Feelings", "Technical Insights"],
    timestamp: 1735224645123,
    excerpt: "...feeling frustrated with the TypeScript compiler...",
    type: "user"
  },
  {
    path: "/home/user/.private-journal/2025-12-20/09-15-22-789012.md",
    score: 0.782,
    text: "Full extracted text content...",
    sections: ["Technical Insights"],
    timestamp: 1734686122789,
    excerpt: "...debugging strategies include checking types...",
    type: "user"
  }
]
*/

// Excerpt generation highlights query-relevant sections
// Scores are computed via cosine similarity between embeddings

```

--------------------------------

### MCP Tool: search_journal for Semantic Search

Source: https://context7.com/obra/private-journal-mcp/llms.txt

The `search_journal` MCP tool enables semantic search across all journal entries using natural language queries and vector similarity matching. It returns ranked results with relevance scores, allowing for conceptually related entries to be found. The tool supports searching both project and user journals and can optionally filter by specific sections.

```typescript
// Search for conceptually related entries
{
  "name": "search_journal",
  "arguments": {
    "query": "times I struggled with TypeScript type errors",
    "limit": 5,
    "type": "both",  // Search project and user journals
    "sections": ["feelings", "technical_insights"]  // Optional filter
  }
}

// Returns structured results:
/*
Found 5 relevant entries:

1. [Score: 0.847] 12/26/2025 (user)
   Sections: Feelings, Technical Insights
   Path: /home/user/.private-journal/2025-12-26/14-30-45-123456.md
   Excerpt: I'm feeling frustrated with the TypeScript compiler today. The error messages are cryptic...

2. [Score: 0.782] 12/20/2025 (project)
   Sections: Project Notes, Technical Insights
   Path: /project/.private-journal/2025-12-20/09-15-22-789012.md
   Excerpt: Discovered that TypeScript's strict mode catches more type errors at compile time...

3. [Score: 0.734] 12/15/2025 (user)
   Sections: Technical Insights
   Path: /home/user/.private-journal/2025-12-15/16-45-33-345678.md
   Excerpt: When debugging TypeScript errors, always check the full error stack...
*/

// Implementation uses cosine similarity between query embedding and stored embeddings
// Embeddings are 384-dimensional vectors from all-MiniLM-L6-v2 model
```

--------------------------------

### List Recent Journal Entries (MCP Tool)

Source: https://context7.com/obra/private-journal-mcp/llms.txt

Browse recent journal entries chronologically. This function is useful for reviewing recent learnings without needing to search. It takes arguments for limit, type (project, user, or both), and the number of days.

```typescript
// List recent entries from the last 7 days
{
  "name": "list_recent_entries",
  "arguments": {
    "limit": 10,
    "type": "both",  // project, user, or both
    "days": 7
  }
}

// Returns chronological list:
/*
Recent entries (last 7 days):

1. 12/26/2025 (user)
   Sections: Feelings, Technical Insights, User Context
   Path: /home/user/.private-journal/2025-12-26/14-30-45-123456.md
   Excerpt: I'm feeling frustrated with the TypeScript compiler today...

2. 12/25/2025 (project)
   Sections: Project Notes
   Path: /project/.private-journal/2025-12-25/11-20-15-567890.md
   Excerpt: Implemented the new authentication flow using JWT tokens...

3. 12/24/2025 (user)
   Sections: World Knowledge, Technical Insights
   Path: /home/user/.private-journal/2025-12-24/09-45-30-234567.md
   Excerpt: Learned about the Model Context Protocol standard today...
*/
```

--------------------------------

### Define Journal Entry Structure (TypeScript)

Source: https://github.com/obra/private-journal-mcp/blob/main/docs/implementation-plan.md

Defines the structure for a journal entry, including content, timestamp, and file path. It also declares the `JournalManager` class for managing journal operations.

```typescript
interface JournalEntry {
  content: string;
  timestamp: Date;
  filePath: string;
}

class JournalManager {
  constructor(journalPath: string);
  writeEntry(content: string): Promise<void>;
  private generateTimestamp(): string;
  private ensureDirectoryExists(date: string): Promise<void>;
  private formatEntry(content: string, timestamp: Date): string;
}
```

--------------------------------

### Generate Missing Embeddings on Server Startup with JournalManager

Source: https://context7.com/obra/private-journal-mcp/llms.txt

The JournalManager automatically scans journal directories for entries lacking embeddings and generates them upon server startup. This ensures immediate search availability. It handles errors gracefully by logging and continuing.

```typescript
import { JournalManager } from './journal';

const journal = new JournalManager('/project/.private-journal');

// Called automatically on server startup
const count = await journal.generateMissingEmbeddings();
// Console: "Generating missing embedding for /project/.private-journal/2025-12-20/14-30-45-123456.md"
// Console: "Generating missing embedding for ~/.private-journal/2025-12-19/09-15-22-789012.md"
// Returns: 2 (number of embeddings generated)

// Process:
// 1. Scans both project and user journal paths
// 2. Finds all .md files in YYYY-MM-DD directories
// 3. Checks if corresponding .embedding file exists
// 4. Generates missing embeddings by:
//    - Reading .md file
//    - Extracting timestamp from path (HH-MM-SS-μμμμμμ)
//    - Calling generateEmbeddingForEntry()
//    - Saving .embedding JSON file
// 5. Continues on errors (logs but doesn't fail)

// Embedding file format (.embedding):
/*
{
  "embedding": [0.023, -0.145, ..., 0.067],  // 384 numbers
  "text": "Extracted searchable text without frontmatter or headers",
  "sections": ["Feelings", "Technical Insights"],
  "timestamp": 1735224645123,
  "path": "/full/path/to/entry.md"
}
*/

```

--------------------------------

### Write Journal Thoughts (JournalManager)

Source: https://context7.com/obra/private-journal-mcp/llms.txt

Core method to route multi-section journal entries to appropriate storage locations and generate embeddings. It takes a project path for initialization and a dictionary of thoughts categorized by section. Files are automatically created with embeddings.

```typescript
import { JournalManager } from './journal';

// Initialize with project path (user path auto-resolves to ~/.private-journal)
const journal = new JournalManager('/path/to/project/.private-journal');

// Write thoughts with automatic routing
await journal.writeThoughts({
  feelings: "Excited about the new feature working!",
  project_notes: "The API endpoint is at /api/v1/data and returns JSON",
  user_context: "Jesse prefers detailed commit messages",
  technical_insights: "Async/await is cleaner than Promise chains",
  world_knowledge: "HTTP/2 multiplexes multiple requests over one connection"
});

// Creates 2 files automatically:
// 1. /path/to/project/.private-journal/2025-12-26/14-30-45-123456.md
//    Contains only: ## Project Notes
//
// 2. ~/.private-journal/2025-12-26/14-30-45-123457.md
//    Contains: ## Feelings, ## User Context, ## Technical Insights, ## World Knowledge

// Each file gets automatic embedding generation for search:
// - Extracts text (removing frontmatter and headers)
// - Generates 384-dim vector via all-MiniLM-L6-v2
// - Saves alongside as .embedding file (JSON)
```

--------------------------------

### Process Thoughts (Journaling)

Source: https://github.com/obra/private-journal-mcp/blob/main/README.md

Allows multi-section private journaling with optional categories for feelings, project notes, user context, technical insights, and world knowledge.

```APIDOC
## POST /process_thoughts

### Description
Writes a new journal entry with optional categories.

### Method
POST

### Endpoint
/process_thoughts

### Parameters
#### Request Body
- **entry** (string) - Required - The content of the journal entry.
- **type** (string) - Optional - Specifies the section for the entry (e.g., 'feelings', 'project_notes', 'user_context', 'technical_insights', 'world_knowledge').

### Request Example
```json
{
  "entry": "I'm feeling optimistic today about the project.",
  "type": "feelings"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Search Journal

Source: https://github.com/obra/private-journal-mcp/blob/main/README.md

Performs semantic search across all journal entries using natural language queries and vector similarity.

```APIDOC
## POST /search_journal

### Description
Searches journal entries semantically.

### Method
POST

### Endpoint
/search_journal

### Parameters
#### Request Body
- **query** (string) - Required - The natural language search query.
- **limit** (integer) - Optional - Maximum number of results to return (default: 10).
- **type** (string) - Optional - Search scope: 'project', 'user', or 'both' (default: 'both').
- **sections** (array of strings) - Optional - Filter search results by specific categories.

### Request Example
```json
{
  "query": "What are the key learnings from the last project?",
  "limit": 5,
  "sections": ["project_notes", "technical_insights"]
}
```

### Response
#### Success Response (200)
- **results** (array of objects) - A list of matching journal entries. Each object contains:
  - **path** (string) - The file path of the entry.
  - **score** (number) - The similarity score of the entry to the query.
  - **title** (string) - The title of the entry.
  - **snippet** (string) - A preview of the entry content.

#### Response Example
```json
{
  "results": [
    {
      "path": ".private-journal/2025-05-31/14-30-45-123456.md",
      "score": 0.95,
      "title": "2:30:45 PM - May 31, 2025",
      "snippet": "Vector embeddings provide semantic understanding..."
    }
  ]
}
```
```

--------------------------------

### List Recent Entries

Source: https://github.com/obra/private-journal-mcp/blob/main/README.md

Retrieves a chronological list of recent journal entries.

```APIDOC
## POST /list_recent_entries

### Description
Lists recent journal entries chronologically.

### Method
POST

### Endpoint
/list_recent_entries

### Parameters
#### Request Body
- **limit** (integer) - Optional - Maximum number of entries to list (default: 10).
- **type** (string) - Optional - Entry scope: 'project', 'user', or 'both' (default: 'both').
- **days** (integer) - Optional - Number of days back to search for entries (default: 30).

### Request Example
```json
{
  "limit": 5,
  "days": 7,
  "type": "user"
}
```

### Response
#### Success Response (200)
- **entries** (array of objects) - A list of recent journal entries. Each object contains:
  - **path** (string) - The file path of the entry.
  - **title** (string) - The title of the entry.
  - **date** (string) - The date and time the entry was created.

#### Response Example
```json
{
  "entries": [
    {
      "path": "~/.private-journal/2025-05-31/14-32-15-789012.md",
      "title": "2:32:15 PM - May 31, 2025",
      "date": "2025-05-31T14:32:15.000Z"
    }
  ]
}
```
```

--------------------------------

### Read Journal Entry

Source: https://github.com/obra/private-journal-mcp/blob/main/README.md

Retrieves the full content of a specific journal entry based on its file path.

```APIDOC
## POST /read_journal_entry

### Description
Reads the full content of a specific journal entry.

### Method
POST

### Endpoint
/read_journal_entry

### Parameters
#### Request Body
- **path** (string) - Required - The file path of the journal entry, typically obtained from search results.

### Request Example
```json
{
  "path": ".private-journal/2025-05-31/14-30-45-123456.md"
}
```

### Response
#### Success Response (200)
- **content** (string) - The full markdown content of the journal entry, including YAML frontmatter.

#### Response Example
```json
{
  "content": "---\ntitle: \"2:30:45 PM - May 31, 2025\"\ndate: 2025-05-31T14:30:45.123Z\ntimestamp: 1717160645123\n---\n\n## Feelings\n\nI'm excited about this new search feature..."
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.