mcp_sqlite_memory_bank project.instructions.md

SQLite Memory Bank Project Instructions (MCP Server Specific)

PROJECT OVERVIEW

Dynamic, agent-friendly SQLite memory bank as FastMCP server. Explicit, discoverable APIs for LLM frameworks.

Core Components: server.py (FastMCP tools), types.py (exceptions), utils.py (error handling), examples/ (usage patterns) Design Principles: Explicit over implicit, type safety, discoverability, consistent error handling, input validation

PROJECT-SPECIFIC DATABASE REQUIREMENTS

• SQLite 3.46+: Leverage JSON columns, generated columns, strict mode, foreign keys, check constraints, and transactions
• Schema Management: snake_case, appropriate constraints, consistent naming
• Storage Patterns: Use create_row('table', {...}) and upsert_memory() for deduplication
• Retrieval Patterns: Use read_rows('table', {'where': 'clause'}) and semantic search for discovery

PROJECT-SPECIFIC PATTERNS

FastMCP Architecture

• server.py: FastMCP implementation with all tool definitions
• types.py: Custom exception classes and type definitions
• utils.py: Utility functions with error handling decorators
• examples/: Example scripts showing usage patterns

SQLite Memory Bank Usage

• Error Responses: Always return {"success": True, "data": result} or error dict
• Custom Exceptions: MemoryBankError → ValidationError, DatabaseError, SchemaError, DataError
• Response Format: {"success": false, "error": "message", "category": "type", "details": {}}
• Decorator: @catch_errors automatically wraps exceptions

FastMCP Tools Development

@mcp.tool()
def tool_name(param: Type) -> ToolResponse:
    """Tool description for LLM discovery."""
    # Implementation with cast(ToolResponse, error_dict) for errors

• Use _impl functions for internal Python calls (decorated functions not callable)
• Always return {"success": True, "data": result} or error dict
• Use Optional[Type] instead of Type = None