[FEATURE] Auto-Format on Save

[divideby0]

Feature Description

Add optional automatic file formatting using external formatters (like Prettier) when Basic Memory writes files. Includes a standalone basic-memory format command for batch formatting existing files.

Problem This Feature Solves

Basic Memory writes .md, .canvas, and .json files without formatting, leading to:

• Inconsistent file styling across projects
• Noisy version control diffs when users manually format files
• Extra manual steps for users who want formatted output
• No standardized formatting for teams without external tooling

Proposed Solution

Auto-Format on Save

Add configuration options to automatically format files after MCP tools write them:

{
  "format_on_save": true,
  "formatter_command": "prettier --write {file}",
  "formatters": {
    "md": "prettier --write {file}",
    "json": "prettier --write {file}"
  },
  "formatter_timeout": 5.0
}

Environment variables:

• BASIC_MEMORY_FORMAT_ON_SAVE=true
• BASIC_MEMORY_FORMATTER_COMMAND="prettier --write {file}"
• BASIC_MEMORY_FORMATTERS='{"md": "prettier --write {file}"}'

Integration points (where formatting hooks in):

• write_note MCP tool
• edit_note MCP tool
• canvas MCP tool

Standalone Format Command

# Format all files in current/default project
basic-memory format

# Format files in specific project
basic-memory format --project my-research

# Format specific file or directory
basic-memory format notes/meeting.md

Key Design Decisions

• Disabled by default (opt-in)
• Formatter errors warn but don't fail the write
• Async subprocess execution with configurable timeout
• Re-reads file after formatting to compute correct checksum
• Per-extension formatters with global fallback

Trade-offs

Formatting adds a subprocess call per file write, which has minor performance overhead and requires external tools (like prettier) to be installed. However, the token efficiency impact is likely negligible or even positive - consistent formatting produces predictable patterns that may be easier for LLMs to parse than inconsistently formatted content.

Alternative Solutions

1. Claude Code hooks - Users can set up post-tool hooks to run prettier, but this only works in Claude Code, not other MCP clients
2. Pre-commit hooks - Requires separate tooling setup and doesn't format on save
3. Editor integration - Requires users to open files in an editor with format-on-save

Additional Context

• PRD with full technical details: .taskmaster/docs/prd.md
• Feature branch: feature/auto-format-on-save
• Uses existing BasicMemoryConfig Pydantic model with env_prefix="BASIC_MEMORY_"

Impact

• Developers: Consistent formatting without manual intervention
• Teams: Standardized output across all team members
• Obsidian users: Properly formatted canvas JSON files
• Version control: Cleaner diffs with consistent styling

[phernandez]

@claude what do you think? What are some options to implement a note formatting feature?

[claude]

Claude finished @phernandez's task in 2m 4s —— View job

---

Note Formatting Feature - Implementation Options

I've analyzed the codebase to understand how auto-formatting could be integrated. Here's a comprehensive breakdown of the options:

---

Current Architecture

File write flow:

1. MCP Tools (write_note, edit_note, canvas) → Call API endpoints via HTTPX
2. API Routers (knowledge_router, resource_router) → Call services
3. Services (entity_service) → Call file_service.write_file()
4. FileService → Writes to filesystem via file_utils.write_file_atomic()

Key integration point: FileService.write_file() (src/basic_memory/services/file_service.py:146-187) is the single bottleneck where ALL file writes happen.

---

Implementation Options

Option 1: Hook in FileService (Recommended)

Where: Add formatting right after file_utils.write_file_atomic() in FileService.write_file()

Pros:

• ✅ Single integration point - catches all writes (MCP tools, sync, imports)
• ✅ Automatic checksum correction (re-read file after formatting)
• ✅ Clean separation of concerns
• ✅ Easy to test and maintain
• ✅ Works with cloud storage (S3FileService would override similarly)

Cons:

• ⚠️ Adds latency to every file write (subprocess overhead ~50-200ms)
• ⚠️ Requires formatter to be installed on system

Implementation sketch:

async def write_file(self, path: FilePath, content: str) -> str:
    # ... existing code ...
    await file_utils.write_file_atomic(full_path, content)
    
    # NEW: Auto-format if enabled
    if self.config.format_on_save:
        try:
            await self._format_file(full_path)
            # Re-read to compute correct checksum
            async with aiofiles.open(full_path, 'r') as f:
                content = await f.read()
        except FormatterError as e:
            logger.warning(f"Formatting failed: {e}")
    
    checksum = await file_utils.compute_checksum(content)
    return checksum

---

Option 2: Post-Write Hook in API Layer

Where: Add formatting in API routers after entity creation

Pros:

• ✅ Only formats user-facing writes (not internal sync)
• ✅ Can customize per-endpoint (e.g., only format notes, not canvas)

Cons:

• ❌ Multiple integration points (knowledge_router, resource_router)
• ❌ Misses files written by sync/import operations
• ❌ Harder to maintain consistency
• ❌ Checksum mismatch issues (would need to re-read and update entity)

---

Option 3: Standalone Service + Manual Integration

Where: Create FormatterService called explicitly from each write point

Pros:

• ✅ Maximum flexibility - choose exactly when to format
• ✅ Testable in isolation

Cons:

• ❌ Requires manual integration at every write point
• ❌ Easy to miss new write paths as codebase evolves
• ❌ More boilerplate code

---

Option 4: External Watch Process

Where: Separate process monitors filesystem and formats on change

Pros:

• ✅ Zero impact on write performance
• ✅ Works with any file source (manual edits, sync, etc.)

Cons:

• ❌ Race conditions with checksums (file changed after write)
• ❌ Complexity (requires inotify/watchdog integration)
• ❌ Doesn't work with cloud storage
• ❌ Basic Memory already has a watch service - would need integration

---

Recommended Approach

Option 1 (FileService hook) is the best choice because:

1. Completeness - Catches ALL file writes automatically
2. Correctness - Checksum recomputation is built-in
3. Maintainability - Single point of change
4. Cloud compatibility - S3FileService can override similarly

Configuration design:

# In BasicMemoryConfig (src/basic_memory/config.py)
class BasicMemoryConfig(BaseSettings):
    # ... existing fields ...
    
    format_on_save: bool = Field(
        default=False,
        description="Automatically format files after writing"
    )
    
    formatter_command: Optional[str] = Field(
        default=None,
        description="Default formatter command (e.g., 'prettier --write {file}')"
    )
    
    formatters: Dict[str, str] = Field(
        default_factory=dict,
        description="Per-extension formatter commands (overrides formatter_command)"
    )
    
    formatter_timeout: float = Field(
        default=5.0,
        description="Formatter subprocess timeout in seconds"
    )

Formatter service:

# New: src/basic_memory/services/formatter_service.py
class FormatterService:
    async def format_file(self, path: Path) -> bool:
        """Format file using configured formatter. Returns True if formatted."""
        extension = path.suffix.lstrip('.')
        command = self._get_formatter_command(extension)
        
        if not command:
            return False
        
        # Run formatter subprocess with timeout
        # Handle errors gracefully (warn but don't fail)
        ...

---

Standalone basic-memory format Command

This would be a simple CLI command that:

1. Discovers files in project (.md, .json, .canvas)
2. Calls FormatterService.format_file() for each
3. Updates checksums in database

CLI structure:

# Format current/default project
basic-memory format

# Format specific project  
basic-memory format --project my-research

# Format specific path
basic-memory format notes/meeting.md

---

Trade-offs Summary

Aspect	Impact
Performance	~50-200ms per file write (subprocess overhead)
Token efficiency	Likely neutral or positive (consistent formatting helps LLMs)
Complexity	Low (single integration point)
Maintenance	Low (isolated service)
User experience	High value (automatic formatting, no manual steps)

---

Next Steps

If you'd like to move forward with this feature:

1. Create FormatterService with subprocess handling
2. Integrate into FileService.write_file()
3. Add config fields to BasicMemoryConfig
4. Add basic-memory format CLI command
5. Write tests for formatter integration
6. Document formatter configuration

Would you like me to implement this? Or would you prefer a different approach?

---

[divideby0]

i'm also working on a pr for it

…

--- Cedric Hurst CEO & Founder | Spantree LLC, a Trifork Company email: ***@***.*** | phone: +1 630.290.3865 http://www.spantree.net Sent via Superhuman ***@***.***>

On Sat, Dec 20, 2025 at 8:21 PM, claude[bot] ***@***.***> wrote: *claude[bot]* left a comment (basicmachines-co/basic-memory#466) <#466 (comment)> Claude Code is working… claude-thinking.gif (view on web) <https://github.com/user-attachments/assets/5ac382c7-e004-429b-8e35-7feb3e8f9c6f> I'll analyze this and get back to you. View job run <https://github.com/basicmachines-co/basic-memory/actions/runs/20403346538> — Reply to this email directly, view it on GitHub <#466 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAEBPJ4P6S4H6BNB65QPC6T4CX72ZAVCNFSM6AAAAACPUYS2V6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMNZYGM3DSNZWHE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[divideby0]

PR is ready #467. but @claude feel free to chime in on my approach