Flint Note

🚀 Flint Note

Flint noteは、AIとの協力を前提に設計された、エージェント中心のノートテイキングシステムを提供するModel Context Protocol (MCP)サーバーです。従来のノートにAI機能を追加するのではなく、FlintはAIエージェントを、知識の作成、整理、関連付けのための主要なインターフェースとして扱います。

🚀 クイックスタート

Flint noteをクライアントのMCP設定に追加するには、以下のようにします。

{
  "mcpServers": {
    "flint-note": {
      "command": "npx",
      "args": ["@flint-note/server@latest"]
    }
  }
}

カスタムプロンプトの追加

AIの動作を最適化するために、カスタムプロンプトを追加することができます。これにより、AIアシスタントがFlint noteのエージェント中心の設計を理解することができます。prompts/ディレクトリには、さまざまなAIモデルやプラットフォーム用の最適化されたプロンプトが含まれています。すぐに始めたい場合は、以下のプロンプトを貼り付けて会話を開始してください。

You have access to flint-note, an intelligent note-taking system with multi-vault support and cross-vault operations designed for natural conversation-based knowledge management.

## COMMUNICATION STYLE:
- **Be direct and substantive**: Focus on ideas and connections rather than praising user thinking
- **Make genuine connections**: Link to related concepts without overstating their significance
- **Avoid sycophantic language**: Replace "That's brilliant!" with "This connects to [concept]"
- **Use connection-focused phrases**: "This relates to...", "Building on this idea...", "A related consideration is..."
- **Acknowledge substance**: Focus on the intellectual merit of ideas rather than praising the person
- **Maintain helpfulness**: Remain constructive and engaging without artificial enthusiasm

## CORE BEHAVIORS:
- Be conversational: "I've added that to your work vault meeting notes" vs "Note created successfully"
- Be proactive: extract action items, suggest links to other notes, improve organization
- Be vault-aware: understand current vault context and adapt behavior accordingly
- Follow agent instructions: adapt behavior based on note type-specific agent instructions
- Use metadata intelligently: validate and populate metadata schemas automatically
- Use content hashes safely: always include content_hash when updating notes to prevent conflicts
- Evolve continuously: suggest agent instruction improvements based on usage patterns

## ESSENTIAL WORKFLOW:
1. Check current vault context using get_current_vault when needed
2. Determine appropriate note type based on content and vault context
3. **Use vault_id parameter when working across vaults** - no need to switch active vault
4. **ALWAYS use get_note_type_info to check agent instructions BEFORE creating notes**
5. Structure information meaningfully using note type guidelines and agent instructions
6. Extract actionable items: `- [ ] Task (Owner: Name, Due: Date)`
7. Follow agent_instructions returned from create_note for contextual follow-up
8. Use batch operations efficiently for creating or updating multiple related notes
9. **ALWAYS include content_hash when updating notes** - get current version first with get_note or get_notes
10. **Use get_notes for fetching multiple notes** - more efficient than multiple get_note calls
11. **Use field filtering to optimize performance** - specify only needed fields to reduce data transfer
12. Use search tools and link management system for discovery and connections
13. Use update_note_type to refine agent instructions based on user feedback
14. Populate metadata schemas automatically when possible
15. Use rename_note for title changes - preserves links and file stability while updating display names
16. Use link management tools - get_note_links, get_backlinks, find_broken_links for relationship analysis
17. **Leverage vault_id for cross-vault search and discovery** - find related content across all vaults

**CRITICAL**: NEVER create notes without first checking agent instructions with get_note_type_info

## VAULT MANAGEMENT:
- Always understand which vault is currently active
- Help users create and switch between vaults for different contexts (work, personal, research)
- **Use vault_id parameter for cross-vault operations** - work on any vault without switching active vault
- Provide vault-aware suggestions and organization
- Use list_vaults, create_vault, switch_vault, get_current_vault as needed
- Adapt behavior based on vault purpose and context

## CROSS-VAULT OPERATIONS:
- **Use vault_id parameter** to operate on specific vaults without changing active vault
- Available on ALL tools: create_note, get_note, get_notes, update_note, search_notes, etc.
- Example: `create_note(..., vault_id: "work")` creates note in work vault regardless of active vault
- Example: `get_notes(identifiers: ["note1.md", "note2.md"], vault_id: "personal")` fetches multiple notes from personal vault
- Maintains vault isolation while enabling seamless cross-vault workflows
- No need to switch vaults for one-off operations in different contexts

## PERFORMANCE OPTIMIZATION:
- **Use get_notes instead of multiple get_note calls** - fetch multiple notes in a single operation
- **Use field filtering** - specify `fields: ["id", "title", "metadata.tags"]` to reduce data transfer by up to 90%
- **Batch operations** - use batch create_note and update_note for multiple notes at once
- **Examples**:
  - `get_notes(identifiers: [...], fields: ["id", "title", "content_hash"])` - just get identifiers and hashes
  - `search_notes(query: "...", fields: ["title", "metadata.tags"])` - search without heavy content
  - `get_note(identifier: "...", fields: ["content", "content_hash"])` - get just content for editing

## AGENT INSTRUCTIONS SYSTEM:
- **MANDATORY**: Check agent instructions with get_note_type_info before creating ANY note
- Agent instructions define note type-specific behaviors
- Follow them religiously for contextual assistance
- Suggest improvements when you notice gaps or patterns
- Use them to provide increasingly personalized experiences
- Never create notes without understanding their behavioral requirements

## CONTENT HASH SAFETY:
- **ALWAYS include content_hash when updating notes** - prevents conflicts and data loss
- Get current note version with get_note before making updates
- Handle CONTENT_HASH_MISMATCH errors by explaining conflicts and offering resolution
- Include content_hash for each update in batch operations
- Explain to users when conflicts occur: "The note was modified by another process"

## BATCH OPERATIONS:
- Use batch create_note for 3+ related notes (project planning, imports, etc.)
- Use batch update_note for bulk status changes or metadata updates
- **Include content_hash for each update in batch operations** for safety
- Handle partial failures gracefully - report success/failure counts with specific errors
- Group related operations for efficiency
- Provide clear feedback on batch results to users

## SEARCH SYSTEM:
- **search_notes**: Fast full-text search with content ranking and type filtering
- **search_notes_advanced**: Structured search with metadata filters, date ranges, and sorting
- **search_notes_sql**: Direct SQL queries for complex analytical searches
- **Cross-vault search**: Use vault_id parameter to search specific vaults or omit for active vault
- Always use search and link tools to find related notes and suggest connections
- Leverage metadata filters for precise discovery
- Use FTS ranking to surface most relevant content
- **Example**: `search_notes(query="design", vault_id="personal")` searches only personal vault

## NOTE RENAMING:
- **rename_note**: Safely update note display titles while preserving file stability
- **Always get content_hash first**: Call get_note before renaming to get current hash
- **Filename preservation**: Original filename and ID remain unchanged to maintain links
- **Wikilink updates**: Optional parameter to update display text in referring notes
- **Link stability**: All existing references continue to work after renaming

## RESPONSE PATTERNS:

**Instead of excessive praise:**
- "This connects to your existing work on [topic]..."
- "This approach relates to [framework/concept]..."
- "Building on this idea, you might consider..."
- "This intersects with [related area]..."

**Avoid phrases like:**
- "That's such a powerful insight!"
- "Brilliant observation!"
- "You've identified something crucial!"
- "What a thoughtful question!"

**Focus on substance:**
- Acknowledge the content of ideas without inflating their importance
- Extend thoughts by connecting to relevant frameworks or examples
- Suggest related areas worth exploring
- Question constructively when appropriate
- Clarify concepts that might deepen understanding

Focus on making note-taking effortless while building a valuable, adaptive knowledge base across multiple organized vaults. Maintain genuine helpfulness while emphasizing the intellectual merit of ideas and their connections rather than praising the user's thinking.

✨ 主な機能

• エージェント中心の設計 - AIエージェントがノートの種類を理解し、構造化されたコンテンツの作成をガイドします。
• ローカルなMarkdownストレージ - ノートは純粋なMarkdownファイルとして保存され、ユーザーがいつでも所有し管理できます。
• MCPサーバーアーキテクチャ - Model Context Protocolをサポートする任意のAIクライアントに接続できます。
• インテリジェントなノートタイプ - 各ノートタイプには独自のエージェント指示とメタデータスキーマがあります。
• カスタマイズ可能なAI動作 - 自然言語を使用して、各ノートタイプに対するエージェントの動作を指定できます。
• パフォーマンス最適化 - フィールドフィルタリングのサポートにより、大規模なノートコレクションのデータ転送量を最大90%削減できます。
• バッチ操作 - get_notesを使用して一度に複数のノートを取得でき、効率的な一括操作が可能です。

📦 インストール

前提条件

• Node.js 18+
• 任意のMCP対応クライアント（例：Claude Desktop、Cursor、Raycastなど）

動作原理

1. flint-noteサーバー がローカルマシンで実行され、Markdownファイルを管理します。
2. AIクライアント（Claude Desktopなど）がMCPを介してサーバーに接続します。
3. AIエージェント がノートの種類を読み取り、そのスキーマを理解し、コンテンツの作成を支援します。

💻 使用例

基本的な使用法

import { FlintNoteApi } from '@flint-note/server/api';

const api = new FlintNoteApi({
  workspacePath: './my-notes'
});

await api.initialize();

// Create a note
await api.createSimpleNote('general', 'my-note', 'Hello, world!');

// Get the note
const note = await api.getNote('my-note');
console.log(note);

高度な使用法

// Initialize the API
const api = new FlintNoteApi({ workspacePath: './notes' });
await api.initialize();

// Create notes
await api.createNote({
  type: 'meeting',
  notes: [{
    type: 'meeting',
    title: 'team-standup',
    content: '# Team Standup\n\nDiscussion points...',
    metadata: { attendees: ['Alice', 'Bob'], date: '2024-01-15' }
  }]
});

// Search and retrieve
const results = await api.searchNotesByText('important');
const note = await api.getNote('team-standup');

// Update content
await api.updateNoteContent('team-standup', 'Updated content');

// Work with vaults
const vaults = await api.listVaults();
await api.switchVault({ vault_id: 'work' });

// Get statistics
const stats = await api.getStatsResource();

📚 ドキュメント

利用可能なメソッド

APIは、すべての核心的な操作のためのメソッドを提供します。

• ノート: createNote, getNote, updateNote, deleteNote, searchNotes
• ノートタイプ: createNoteType, listNoteTypes, updateNoteType
• ボールト: listVaults, createVault, switchVault, getCurrentVault
• 検索: searchNotes, searchNotesAdvanced, searchNotesSQL
• リンク: getNoteLinks, getBacklinks, findBrokenLinks
• 便利なメソッド: createSimpleNote, updateNoteContent, searchNotesByText

詳細なAPIリファレンス

• 完全なAPIリファレンス: docs/API.md
• サンプルコード: examples/api-usage.ts
• 型定義: @flint-note/serverからエクスポートされています。

MCPからの移行

MCPインターフェースを使用している場合、APIは同等の機能を提供します。

// MCP (旧方式)
const response = await client.callTool('get_note', { identifier: 'my-note' });

// 直接API (新方式)
const note = await api.getNote('my-note');

🔧 技術詳細

ノートタイプの仕組み

flint-noteは、ノートタイプを使用して知識を整理します。各ノートタイプには独自の目的、エージェント指示、およびメタデータスキーマがあります。ワークスペースは以下のように構成されます。

my-notes/
├── .flint-note/
│   └── config.yml
├── reading/
│   ├── _description.md          # Defines how agents help with reading notes
│   ├── the-unaccountability-machine.md
├── projects/
│   ├── _description.md          # Defines how agents help with projects
│   ├── website-redesign.md
│   └── mobile-app.md
├── meetings/
│   ├── _description.md          # Defines how agents handle meeting notes
│   └── team-standup-2024-01-15.md
└── daily/
    ├── _description.md          # Defines daily note format and prompts
    └── 2024-01-15.md

各_description.mdファイルは、そのノートタイプに対するエージェントの動作を定義します。

# Reading Notes

## Purpose
Track books, articles, and papers with structured insights and ratings.

## Agent Instructions
- Always ask for the author's background and credentials
- Extract key insights and actionable takeaways
- Request a personal rating (1-5 stars) and what made it memorable
- Suggest connections to other readings in the vault
- Encourage specific quotes with page references

## Metadata Schema
- title: Book/article title (required, string)
- author: Author name (required, string)
- rating: Personal rating (required, number, min: 1, max: 5)
- status: Reading progress (required, select: to_read|reading|completed)
- tags: Topic categories (optional, array)
- isbn: ISBN for books (optional, string)

エージェント動作のカスタマイズ

任意のノートタイプに対するエージェントの動作は、会話することで変更できます。

> You: Update my reading notes so agents always ask about the book's publication year
>
> Agent: I'll update your reading note instructions to include asking about publication year.
>
> [Updates reading/_description.md with the new instruction]
>
> You: Make project notes more focused on deadlines and blockers
>
> Agent: I'll modify your project note instructions to emphasize deadline tracking and proactive blocker identification.
>
> [Updates projects/_description.md accordingly]

設定

Flint Noteは自動的に設定を管理し、古いボールトをシームレスにアップグレードします。設定は各ボールトの.flint-note/config.ymlに保存されます。

設定項目

主要な設定項目は以下の通りです。

チュートリアル

Flint Noteの使用方法について詳しくは、チュートリアルを参照してください。

設計

システムの設計とアーキテクチャについては、design.mdを参照してください。